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COURSE DESCRIPTION 


F1i5C PL/I Programming with Multics Subroutines 


Duration: Five Days 


> Intended For: Advanced Multics PL/I programmers who need to use Multics 
subroutines to perform I/0, manipulate files in the 
storage system, and/or write commands and active 
functions. 


Synopsis: | This course introduces the student to the system 
' subroutine repertoire to include subroutines that: 
create, delete, develop pointers to, and return status 
information about storage system entities (hes ); perform 
Stream and record I/0 to files and devices via I/0 
Switches (iox_); enable command and active function 
procedures to properly interface to the standard command 
processing environment (cu_). Interactive workshops 
are included to reinforce the material presented. 


Objectives: Upon completion of this course, the student should be 
able to: write PL/I programs containing calls to system 
Subroutines which: . 


7. Create, destroy, and obtain status information on 
segments, directories, and links. . 


2. Address and manipulate data directly in the virtual 
memory (without input/output statements) 
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3. Interface directly with the Multics I/O System (ioa , 
iox ). 


4, Implement “system standard" commands and active 
functions. 


Prerequisites: Advanced Multies PL/I Programming (F15B) or equivalent 
“experience. 
a 


| i 


Major Topics: Advanced Use of Based Variables 
~ Subroutine Interfaces to the Storage System 
and ACL 
Multics Implementation of Condition Handling 
The Multics I/O System 
Writing Commands and Active Functions 
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F15C TOPIC MAP 
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STUDENT BACKGROUND 


PL/I Programming with Multics Subroutines (F15C) 


NAME: | PHONE: 


‘TITLE: 


COMPANY ADDRESS: 


MANAGER: OFFICE PHONE: 


INSTRUCTOR'S NAME: 


Do you meet the prerequisite as stated in the "Course Description" 
of the student text? If yes, check "a" or "b", 
If no, check "ce" or "qd", 


a { ] Prerequisite satisfied by attending course indicated in "Course 
Description". 


e {[ ] Elected or instructed to attend course anyway. 


d { ] Was not aware of prerequisite. 


What related Honeywell courses have you attended? Furnish dates 
and instructors if possible. 


(PLEASE TURN OVER) 
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STUDENT BACKGROUND 


PL/I Programming with Multics Subroutines (F15C) 


Check the boxes for which you have any related experience. (May 
be other than Honeywell's) 


C J] PL1 C ] COBOL — C] FORTRAN [ ] ASSEMBLY 


C ] JCL . [ ] OPERATIONS {-] Gcos C ] MULTICS 
C ] NPS {[ ] GRTS C ] CP6 C ] OTHER 


Detail any experience you have had which is related to the 
material in this course. 


Objectives for attending this course (May check more than one). 
] Require information to provide support for a system 
To maintain an awareness of this product 


To evaluate or compare its potentials 


[ee set ee | 


nm" 


Need update from a previous release 


] 
J 
] Required to use or implement 
] 
] Require a refresher 

] 


Other: 
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HONEYWELL MARKETING EDUCATION 
COURSE AND INSTRUCTOR EVALUATION FORM 


INSTRUCTOR 
COURSE 
START DATE 
LOCATION 


STUDENT NAME (OPTIONAL) 


In the interest of developing training courses of high quality, 
and then improving on that base, we would like you to complete 
this questionnaire. Your information will aid us in making 
future pavisions and improvements to this course. Both the 


instructor and his/her manager will review these responses. 


Please complete the form and return it to the instructor 
upon the completion of the course. In questions 1 through 
14, check the appropriate box and feel free to include additional 
comments. Attach additional sheets if you need more room 
for comments. Be objective and ‘concrete’ in your comments 


-- be critical when criticism is appropriate. 


ix 
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TOPIC i 


“Review of PL/I Attributes 


Classification of Attributes ... ay oe" 
Usage Examples of Selected Attributes. 
Aggregate Descriptors. 


es « s e es e e e es 
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Topic I REVIEW OF PL/1 ATTRIBUTES Toric I 


OBJECTIVES: 


Upon completion of this toric, students should be able toa: 


1. 


Declare variables in PL/1 usins full ranse of variable 
attributes. 


Determine which instance of a variable is beings referenced at 
any given Point in a Program. 


Manirpulate storage asgresates (arrays and structures). 


Write and use external procedures. 


Set up the proper entry declarations to use external 
Procedures. 
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CLASSIFICATION OF ATTRIBUTES 


@ A REVIEW LIST OF ATTRIBUTES. STARRED ATTRIBUTES ARE COVERED IN 
DETAIL IN TOPICS 2, 3 AND 4. THIS CHAPTER PRESENTS USAGE EXAMPLES 
TO REVIEW/CLARIFY SOME OF THE NON-STARRED ATTRIBUTES 


storage description 
storage type 
data type 
computational 
arithmetic 
mode: real complex 
Scale: fixed float 
base: binary decimal 


precision: precision( p,q) 
String 


string type: character(n) bit(n) picture"™ps" 
variability: varying nonvarying 
non-computational 


address 
Statement: label entry format 
data 
locator: pointer*® offset* 
file: file 


; area: areéea(n)# 
aggregate type 
array: dimension(bp,...) 
structure: structure member 
alignment: aligned unaligned 
management class 
storage class 
allocation: automatic static controlled* based(1lq)* 
sharing: based(lq)* defined(r)* position(i)* parameter 
scope: internal external 


category: variable constant 
initial: initial (x,...) 
usage description 
entry: entry(d,...) returns(d,...) options(variable) 
offset: offset(a)*# 
file constant 
Operation: input output update 
organization . 
stream: stream print environment(interactive) 


record: record sequential direct keyed 


environment(stringvalue) 
non-valued names 


compile time: liker 
intrinsic names: builtin condition* 
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USAGE EXAMPLES OF SELECTED ATTRIBUTES 


@ ARITHMETIC DATA TYPES 
§ del x real fixed binary precision (17,0) aligned; 
f del x; /* SAME AS PREVIOUS DECLARATION #*/ 


1 del salary float decimal (6); 


@ STRING DATA TYPES 
0 del string_1 char(4) init ("ABC"); 


9 del string _2 char(4) varying init ("ABC"); 


string 2 
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USAGE EXAMPLES OF SELECTED ATTRIBUTES 


@ STATEMENT LABEL PREFIX (DECLARED BY USAGE, NOT IN FORMAL DECLARATION) 


J continue_i: x = x + 1; 


0 output_1: format (a(9),f(6,2)); 


0 prog_1: proc; 


] alternate: entry (a,b); 


@ ALIGNMENT 
) del string char(4) aligned; 


J del number fixed bin unaligned; 


@ STATIC VS. AUTOMATIC 


9 del a init(d); 
del b init(0) static; 


CNN RRS Oe 
e 
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/* label internal constant */ 


/® 


/* 


/* 


/* 


format internal constant */ 


entry constant #*/ 


entry constant */ 


DEFAULT IS unaligned */ 


DEFAULT IS aligned */ 


automatic BY DEFAULT #*/ 
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USAGE EXAMPLES OF SELECTED ATTRIBUTES 


@ AGGREGATES 


1 del array 1 (10); 
del array 2 (-6:4); 
del array 3 (10,3); 
del array 4 dimension (5); 


J STRUCTURE 


§ del 01 x structure, 
02 y char(8) member, 
02 z fixed bin(35) member; 


0 del 01 x, 02 y char(8), 02 z fixed bin(35); 


0 LIKE ATTRIBUTE 
0 del 1 record_1, 
2 employee info, 
3 name char(10), 
3 salary fixed dec(10,2); 
0 del 1 record 2 like record_1; 


1 del 1 employee like record_1.employee_info.name; 


@ PARAMETER 


 sub_1: proce (a,b); 


del a char(3) parameter; 
del b char(6); /* parameter ATTRIBUTE USUALLY OMITTED #/ 
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@ USAGE EXAMPLES OF SELECTED ATTRIBUTES 


@ SCOPE OF VARIABLES 


0 <A: proc; 


/* SOURCE SEGMENT A.pl1 #/ 


del x external; % 4Stgtic by debault+/ 


del y; 


B proc; 
del xX; 
end B; 
end A; 


J C: proce; 


del x external; 


end C; 
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7/*® SOURCE SEGMENT C.pli #/ 


/* SOURCE SEGMENT D.pl1 #/ 
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USAGE EXAMPLES OF SELECTED ATTRIBUTES 


@ VARIABLE VS. CONSTANT 


J del x internal static init (125) options (constant); 
del (file_1, file 2) file; 
del file _out file variable; 


file out = file 2; 
put file (file_out) list ("Test line"); 


1 TYPES OF IDENTIFIERS THAT ARE USUALLY USED AS CONSTANTS, BUT MAY 
BE DECLARED AND USED AS VARIABLES: label, entry, format, file 


@ INITIALIZATION 


9 del array _1(5) init(1,2,3,4 
del array 2(5) init(1,2,(3) 
1,2,3 


- /* LAST 3 ELEMENTS UNDEFINED */ 
del array 3(3,2) init( ; 


5,6); 


® ENVIRONMENT ATTRIBUTES 


1 open file (sysprint) stream output environment (interactive); 


put list ("line 1"); /* LINEFEED ADDED AT END AUTOMATICALLY #*#/ 
put list ("line 2"); 


open file (stream file) environment (stringvalue) record input 
title ("record stream_ user_input"); 


read file (stream file) into (line); 


/* MAKES POSSIBLE TAKING ENTIRE LINE FROM TERMINAL WITH EMBEDDED 
BLANKS WITHOUT USING QUOTES */ 
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AGGREGATE DESCRIPTORS 


@ DESCRIPTORS DESCRIBE THE DATA TYPE AND LAYOUT OF AN IDENTIFIER WITHOUT 
REFERENCE TO ANY VARIABLE NAMES OR IDENTIFIERS 


@ DESCRIPTORS ARE USED IN "PARAMETER DESCRIPTOR" LISTS, AND IN "RETURNS 
DESCRIPTOR" LISTS 


J EXAMPLES 
1 declare foo$bar entry (fixed bin, ptr, char(*)); 


J declare how_many entry (fixed bin) returns (fixed dec(3,0)); 
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AGGREGATE DESCRIPTORS 


@ DESCRIPTORS ARE FORMED FOR AGGREGATES AS FOLLOWS: 


1 ARRAY DESCRIPTORS 
) ARE DERIVED BY ELIMINATING THE IDENTIFIER FROM THE DECLARATION 


1 THE ARRAY BOUNDS MAY BE PRECEDED BY THE ‘dimension' OR '‘'dim' 
KEYWORD, OR THE KEYWORD MAY BE OMITTED IF THE ARRAY BOUNDS 
PRECEDE THE DATA TYPE 


EXAMPLES 
] del X(12,3) fixed dec(7); 
1 del get_X entry ((12,3) fixed dec(7)); 


J del return _X entry() returns (dim(12,3) fixed dec(7)); 


1 STRUCTURE DESCRIPTORS 


I ARE DERIVED FROM THE DECLARATION AS FOLLOWS: 
1 ELIMINATING ALL IDENTIFIERS 
NORMALIZING THE LEVEL NUMBERS 


1 THE KEYWORDS ‘structure’ AND 'member' MAY BE OMITTED FROM THE 
DESCRIPTORS 
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AGGREGATE DESCRIPTORS 


) EXAMPLE 


del 1A aligned, 
2 C(3) fixed bin, 
2 F ptr; 


J del get A entry (1 structure aligned, 2 dim(3) fixed bin 
member, 2 ptr member); 


J del returns A entry () returns (1 aligned, 2 (3) fixed bin, 
2 ptr); 


J del get_A entry (1 like A); 


J del returns A entry () returns (1 like A); 
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(End Of Topic) 


Considering the stated objectives of this course, rate the overall 
length of the course. 


CAN'T TOO ABOUT TOO 


JUDGE SHORT RIGHT LONG 
COMMENTS 


Considering the objectives, rate the technical level at which the 
course was taught. 


NOT 
CAN'T TECH ABOUT TOO 
JUDGE ENOUGH RIGHT TECH 

[Lo] ECLreztrtestrtettfTfsfrfesestfeeyrfthmcseT QO 


COMMENTS 


Considering the objectives, rate the emphasis placed on the more 
important topics. 


CAN'T 

JUDGE POOR GOOD EXCELLENT 
CC SS SS AS 
COMMENTS 


Rate the sequence in which the topics were presented. 


CAN'T : 

JUDGE POOR GOOD EXCELLENT 
[Co J] CTT ZzaTtTTTtTtTs Tsertyr tol. 
COMMENTS 
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56 


Rate the format and quality of the learning materials (slides, 
student handbooks, supplementary handouts, etc.). 


CAN'T 

JUDGE POOR GOOD | EXCELLENT 
Po} E.R. 2 Fo fT 5 fT 6 ft eT ss TS 
COMMENTS 


Rate the amount of time given for the completion of the workshops. 


TOO TOO 
CAN'T LITTLE ABOUT MUCH 
JUDGE TIME RIGHT TIME 


COMMENTS 


Rate the workshops' ability to relate back to and reinforce the 
material presented. 


CAN'T 
JUDGE POOR GOOD EXCELLENT 
COMMENTS | 


Rate the physical condition of the classroom (space available, 
temperature, lighting, etc.). 


CAN'T 


JUDGE POOR GOOD EXCELLENT 


a) ee eer 
COMMENTS 


at 


Rate the physical condition of the lab or workshop room. (systems 
configuration, space available, learning tools, terminals, tables, 
etc.). 


CAN'T 
JUDGE POOR GOOD EXCELLENT 
COMMENTS 


Rate your instructor's demonstrated knowledge of the course material. 


CAN'T : 
JUDGE POOR GOOD EXCELLENT 
COMMENTS 


Rate your instructor's ability to convey the technical aspects of 
the various topics. 


CAN'T 
JUDGE POOR GOOD EXCELLENT 
COMMENTS 


Rate the classroom and workshop assistance given you by your 
instructor. 


CAN'T 

JUDGE POOR GOOD EXCELLENT 
ee i 1 I 2 ; c T a ! 5 I a I 7 i 5 eee 
beeen 
COMMENTS 
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' 13. 


14. 


15. 


16. 


Rate the instructor's ability to create an environment in which 
you felt free to ask questions. 


CAN'T 
JUDGE POOR GOOD EXCELLENT 
Lo] Cit trea Ts Tatts fot 7 tT 5 ft 3] 
COMMENTS | 


Rate the relevance of the skills learned in the course with respect 
to your job or further training. 


CAN'T | 
JUDGE POOR GOOD EXCELLENT 
COMMENTS 


What did you like most about this course? 


What did you like least about this course? 
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17. 


18. 


Other comments please: 


Of the following job categories, check the ones which most nearly 
represent the bulk of your experience, and to the right of your 
responses indicate the number of years you have acted in that 
capacity. 


C] Applications Programmer. . .. years 
[] Field Engineering Analyst... years 
[] Managers. scsi Sick ee ee Wee years 
[] Marketing Analyst. ...... years 
[1 Salesperson. . .- ++ +++ «+ years 
[] Secretary. ..... + ee ee Tououyears 
[] Systems Analyst. ......+. years 
[] Systems Programmer .....-. ___years 


Ply. OGMGP ax a wings Se G: eeere: etn ee we years 


Please give "other" title 
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Topic II. PL/1 STORAGE MANAGEMENT Topic II 
OBJECTIVES: 
Uron completion of this topic, students should be able to: 


1. Allocate and free controlled variables to imelement a stack 
or a vVariable-extent data item such as a string or array. 


2. Use defined variables to chanse the interpretation of a 
Farticular area of storase. 


3. Maniepulate cross-sections of arrays usins “isub'-defined 
variables. 
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DECLARING PL/I VARIABLES 


_ @ THE DECLARATION OF AN IDENTIFIER IS USUALLY DIVIDED INTO TWO PARTS 


) THE STORAGE TYPE 
] DESCRIBES THE TYPE OF VALUES WHICH CAN BE ACCOMMODATED 


§ DESCRIBES THE AMOUNT AND INTERPRETATION OF STORAGE GENERATED 


{ THE STORAGE MANAGEMENT CLASS 
1 SPECIFIES VARIOUS INFORMATION ABOUT THE HANDLING OF THE STORAGE 
GENERATED FOR THE IDENTIFIER INCLUDING 
0 THE ALLOCATION AND FREEING MECHANISM TO BE USED 
J) THE LOCATION OF THE STORAGE TO BE GENERATED 
) INITIALIZATION OF STORAGE 


1 AN EXAMPLE 


f dcl x real fixed binary(10,0) automatic variable init(5); 


q "real fixed binary(10,0)' IS THE STORAGE TYPE 
) ‘automatic variable init(5)' IS THE STORAGE MANAGEMENT CLASS 
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DEFINING THE PL/I STORAGE MANAGEMENT CLASS 


@ FOUR ATTRIBUTES SPECIFY THE STORAGE MANAGEMENT CLASS 


J THE ‘usage category' ATTRIBUTE 
0 DESCRIBES HOW THE STORAGE IS USED 
J VALUES ARE 'variable' AND ‘constant! 


1 MOST OFTEN, THE USAGE CATEGORY ATTRIBUTE IS OMITTED 


l THE 'scope' ATTRIBUTE 
0 PARTIALLY DETERMINES THE REGION IN WHICH THE STORAGE IS ALLOCATED 
Q AFFECTS THE ACCESSIBILITY OF THE IDENTIFIER 


0 VALUES ARE ‘internal' AND ‘external’ 


0 THE ‘storage class' ATTRIBUTE 


0 SELECTS THE MECHANISM TO BE USED FOR THE ALLOCATION AND FREEING 
OF THE STORAGE GENERATED 


s 


0 VALUES ARE '‘automatic', 'static', '‘controlled', 'based', 
*defined' AND ° parameter’ 


0 THE ‘initial value' ATTRIBUTE 


1 WHEN PRESENT, SPECIFIES A VALUE TO BE ASSIGNED TO THE IDENTIFIER 
WHEN IT IS ALLOCATED 


f VALUE IS ‘initial (value list)’ 
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DEFINING THE PL/I STORAGE MANAGEMENT CLASS 


ABBREVIATIONS AND DEFAULTS 


@ VALID ABBREVIATIONS FOR STORAGE MANAGEMENT ATTRIBUTES 


ATTRIBUTE ABBREVIATION 
internal int 
external ext 
automatic auto 
controlled etl 
defined def 
parameter param 


initial init 


@ STORAGE MANAGEMENT DEFAULT VALUES 


OMITTED ATTRIBUTE DEFAULT VALUE 


usage category | 'variable' 
= (exception:'constant' if the data 
type is 'entry' or 'file') 


scope ‘internal’ 
(exception:'external' if the data 
type is tentry' or 'file') 


storage class ‘automatic’ 
(exception: 'static' if the 
‘external' attribute is 
present or implied) 


1 NOTE: THE DEFAULTS APPLY TO IDENTIFIERS DECLARED IN A FORMAL 
DECLARATION STATEMENT. FOR EXAMPLE: 


1 A LABEL FORMALLY DECLARED IS A variable BY DEFAULT 


1 A LABEL DECLARED BY USAGE AS A LABEL PREFIX IS A constant 
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‘eontrolled' STORAGE CLASS 
CHARACTERISTICS 


@ ‘controlled' STORAGE ALLOWS THE PROGRAMMER TO CONTROL THE GENERATION 
- QF STORAGE FOR A VARIABLE 


IT IS DRIVEN BY EXPLICIT PROGRAM STATEMENTS 


STORAGE IS ALLOCATED BY THE ‘allocate' STATEMENT, AND FREED BY 
THE 'free' STATEMENT 


A 'controlled' VARIABLE IS THEREFORE AVAILABLE FOR WHATEVER PORTION 
OF EXECUTION OF THE PROGRAM THE PROGRAMMER DESIRES 


A SMALL CONTROL BLOCK ASSOCIATED WITH THE 'controlled' VARIABLE 
IS USED TO LOCATE ITS CURRENTLY ALLOCATED STORAGE 


‘controlled' VARIABLES CAN BE "STACKED" 


THEY CAN HAVE EITHER 'internal' OR ‘external' SCOPE (internal IS 
THE DEFAULT) 
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*cgontrolled' STORAGE CLASS 
ALLOCATION AND FREEING 


@ A ‘controlled’ VARIABLE IS ALLOCATED BY EXECUTION OF THE ‘allocate’ 
STATEMENT 


1 allocate id; 


@ A ‘'controlled' VARIABLE IS FREED BY THE EXECUTION OF THE '‘'free' 
STATEMENT 


1 free id; 


) free idi, id2, ..., idN; 
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'controlled' STORAGE CLASS 
STACKING 'controlled' VARIABLES 


@ PL/I ALLOWS US TO ALLOCATE A ‘controlled’ VARIABLE MORE THAN ONCE 
- BEFORE FREEING ITS STORAGE 


I 


THE HISTORY OF ALLOCATIONS FOR EACH VARIABLE IS MAINTAINED ON A 
STACK SO THAT: 


EACH ‘allocate' STATEMENT LEAVES EARLIER ALLOCATIONS OF THAT 
VARIABLE UNDISTURBED 


A 'free' STATEMENT FREES THE MOST RECENTLY ALLOCATED SPACE 
FOR THAT VARIABLE 


EACH TIME THE VARIABLE IS REFERENCED, THE ONE "ON THE TOP OF 


THE STACK" IS ACCESSED (MOST RECENTLY ALLOCATED BUT NOT FREED) 


EXAMPLE 


Pi: proc; 
del x float bin controlled; 


- . (Computation #1) 


allocate x; 
x = 10; 
- « e« (Computation #2) 


allocate x; 
x = 20; 
- « « (Computation #3) 


free x; 
_« « « (Computation #4) 


free xX; 
- « e« (Computation #5) 
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‘controlled’ STORAGE CLASS 
VARIABLE EXPRESSIONS IN ATTRIBUTES 


@ WHEN A ‘controlled' VARIABLE IS ALLOCATED, ANY EXTENT EXPRESSIONS 
AND INITIAL VALUE EXPRESSIONS ARE EVALUATED 


) EXTENTS ARE ARRAY BOUNDS, MAXIMUM STRING LENGTH, OR AREA SIZE 
1 EXTENTS MUST BE SET BEFORE THE EXECUTION OF AN 'allocate' STATEMENT 
) EXTENTS ARE SAVED IN A SYSTEM TEMPORARY 


) EXAMPLE 


Pi: proc; 


del n fixed bin init(0); 
del A(n+2) float bin controlled init((n-2)0) 


n’s-23 

allocate A; 

hs Os /*HAS NO EFFECT ON EXTENT#/ 
put skip list (A); 

free A; 
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"controlled' STORAGE CLASS 
GUIDELINES FOR USING ‘controlled’ STORAGE 


we EE ee 0 oe 


@ ‘'‘controlled' STORAGE IS GENERALLY MORE EXPENSIVE THAN THE BUILT-IN 
STORAGE MANAGEMENT MECHANISM OF AUTOMATIC OR STATIC STORAGE CLASSES 


@ POSSIBLE APPLICATIONS: 


‘Y WHEN A STACK OF VARIABLES IS NEEDED (THIS ALLOWS A PROGRAM WHICH 
USES STATIC VARIABLES TO BECOME REENTRANT BY REPLACING STATIC 
VARIABLES WITH ‘controlled' VARIABLES) 


1 WHEN AN EXTERNAL VARIABLE MUST HAVE VARIABLE EXTENTS ('based' 
VARIABLES, WHICH COULD HAVE VARIABLE EXTENTS, CANNOT HAVE 'external' 
SCOPE ) 


0 WHEN CONTROLLING THE AMOUNT OF STORAGE REQUIRED FOR A PROGRAM 
BECOMES CRITICAL 
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‘controlled! STORAGE CLASS 
GUIDELINES FOR USING ‘controlled' STORAGE 


@ NOTE: PROGRAMS USING ‘controlled’ VARIABLES SHOULD PROVIDE AN ‘on 
unit' FOR THE ‘cleanup’ CONDITION IN ORDER TO FREE ANY ALLOCATED 
STORAGE 


1 THE ‘allocation' BUILTIN FUNCTION RETURNS (IN A fixed bin(17)) 
THE CURRENT ALLOCATION DEPTH OF STORAGE FOR A 'controlled' VARIABLE 


J EXAMPLE 
del cleanup condition; 
del x controlled; 
on cleanup begin; 


do i= 1 to allocation (x); 
free x; 


Not To Be Reproduced 2-9 F15C 


'defined' STORAGE CLASS 
CHARACTERISTICS 


@ A 'defined' VARIABLE IS USED TO ASSOCIATE A NEW NAME WITH AN EXISTING 
VARIABLE OR PART OF AN EXISTING VARIABLE 


@ IT SUPPLIES A POTENTIALLY DIFFERENT INTERPRETATION (REDEF INITION) 


OF 


AN EXISTING GENERATION OF STORAGE 


IT MUST HAVE THE SAME DATA TYPE AS THE PART OF THE BASE VARIABLE 
BEING REDEFINED (EXAMPLE: A BIT STRING CANNOT BE 'defined' ON A 
CHARACTER STRING) 


IT ALWAYS HAS 'internal' SCOPE 


SINCE IT NEVER HAS STORAGE ALLOCATED FOR IT, A ‘defined' VARIABLE 
CANNOT HAVE AN ‘initial' ATTRIBUTE 


@ NOTE: USE OF ‘'defined' VARIABLES IS NOT THE SOLE MEANS OF 
"REDEFINITION" OF VARIABLES ('based' VARIABLES WILL BE DISCUSSED 
LATER ) 
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'defined' STORAGE CLASS 
CHARACTERISTICS 


@ THE ‘defined’ ATTRIBUTE CONSISTS OF THE KEYWORD ‘defined' FOLLOWED 
BY A REFERENCE TO A BASE VARIABLE 


@ THERE ARE THREE WAYS TO USE 'defined' VARIABLES: 
] SIMPLE DEFINING 
1 STRING OVERLAY DEFINING 


1 ‘tisub' DEFINING 
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‘defined’ STORAGE CLASS 
SIMPLE DEFINING 


@® EACH SCALER IN THE 'defined' VARIABLE AND THE CORRESPONDING SCALER 
IN THE BASE VARIABLE HAVE IDENTICAL STORAGE TYPES 


1 EXAMPLE 1 


del array(5,5) char(4); 

del same ~array(5, 5) char (4) defined array; 
del vector_1(5) char (4) defined array; 

del vector 2(5) char(4) defined array(2,1); 


f EXAMPLE 2 


del ia, 
2 b(n), 
3 ¢ float bin, . 
3 d float bin, 
2 e char(§); 


del x float defined(a.b(i-2).d); 
del Y(n) float defined(a.b(*) .d); 
del 1 z defined(a.b(j)), 


221 float bin, 
2 z2 float bin; 


t 


NOTE: THE BASE VARIABLE MAY NOT BE A 'defined' VARIABLE OR A NAMED 
CONSTANT 
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'defined' STORAGE CLASS 
STRING OVERLAY DEFINING 


@ <A STRING 'defined' VARIABLE IS MAPPED ONTO ALL OR PART OF THE STORAGE 
OF A STRING BASE VARIABLE | 


] VALID FOR ALL STRING TYPES AS LONG AS THEY ARE ‘nonvarying unaligned' 
0 MUST MATCH BITS ONTO BITS OR CHARACTERS ONTO CHARACTERS 
1 PICTURED STRINGS CAN BE USED AS THE BASE VARIABLE, A FACT THAT 


PROVIDES 'defined' STORAGE ONE OF ITS MOST POWERFUL FACILITIES 


1 EXAMPLE 


dei a pic "999v.999es99"; 
del exponent char (3) defined (a) position (9); 


] THE 'position' OR 'pos' ATTRIBUTE CAN BE USED TO START THE 'defined' 
VARIABLE AT SOME BIT OR CHARACTER POSI N OTHER THAN THE FIRST 
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'defined' STORAGE CLASS 
STRING OVERLAY DEFINING 


0 EXAMPLES 


del A(5) char(2) unal; 
del B char(8) def(A); 
del i C def(A), 
2 X char(5) unal, 
2 Y char(5) unal; 
del D char(5) def(A) pos(6); 
del E char(5) def(A(2)) pos(2); 


A(1) A(2) A(3) A(4) A(5) 


oe Sk A 

C.X_ C.Y 
. tae ee 
? 3 a 
ee ee 


> 
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‘defined' STORAGE CLASS 
‘isub' DEFINING 


@ A FACILITY OF PL/I WHICH ALLOWS A 'defined' ARRAY TO MAP ONTO A 
BASE ARRAY IN A SPECIALIZED MANNER 


l THE VALUE OF THE ‘isub' REFERS TO THE SUBSCRIPT OF THE DEFINED 
ARRAY, NOT THE BASE ARRAY 


1 EXAMPLE 


del AC(3,4) float bin; 

del Q(3) float bin defined A(1sub,4); 

del TRANS(4,3) float bin defined( A(2sub,1sub)); 
Q(1) --> AC1,4) 
Q(2) -=-> a(2,4) 


Q(3) ==> AC3,4) 
0 THE ARRAY 'Q' DEFINES THE FOURTH COLUMN OF 'A' 


1 THE ARRAY 'TRANS' REPRESENTS THE TRANSPOSE OF ARRAY 'A' 


0 IT REPRESENTS AN INTERPRETATION OF 'A' STORED IN COLUMN-MAJOR 
ORDER INSTEAD OF ROW=-MAJOR ORDER c 


1 THIS CAN BE USEFUL FOR PASSING ARRAY ARGUMENTS FROM FORTRAN 
TO PL/I PROGRAMS AND VICE VERSA 
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'defined' STORAGE CLASS 
‘isub' DEFINING 


1 CONSIDER A PL/1 2 X 2 ARRAY: 


A(1,1) 


1 A(1,2) 


it 
Nw 


A(2,1) 


i 
= 


3 A(2,2) = 


] PL/1 WOULD STORE IT IN MEMORY IN ROW MAJOR ORDER 


Re EAEEES 


) FORTRAN WOULD, HOWEVER, STORE IT IN COLUMN MAJOR ORDER 


WHERE FORTRAN EXPECTS TO FIND A(2,1) 


PL/I MUST THEREFORE PASS FORTRAN A TRANSPOSE! 


| del A(2;2) fixed bin; 
del transpose A (2,2) fixed bin 
defined A(2sub,1sub); 


call fortran_prog (transpose A); 
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‘defined' STORAGE CLASS 
GUIDELINES FOR USING 'defined' STORAGE 


‘defined' STORAGE MANAGEMENT IS "IN COMPETITION" WITH 'based' STORAGE 
MANAGEMENT 


1 'based' STORAGE MANAGEMENT IS MUCH MORE GENERAL 


1 FOR MULTICS, 'based' IS GENERALLY PREFERRED OVER ‘'defined' STORAGE 
MANAGEMENT . 


USUALLY USED ONLY FOR THE ONE UNIQUE FEATURE PROVIDED -- ‘isub' 
DEFINING 


YOU ARE NOW READY FOR WORKSHOP 
#1 
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(End Of Topic) 
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Toric Iil BASED STORAGE ; Topic III 
OBJECTIVES: 
Upon comeletion of this toric, students should be able to: 


1. Allocate and free based variables in the same manner as 
controlled variables. 


2. Differentiate between packed and unpacked Pointers. 


3. Use builtin functions to manipulate locator variables 
(pointers and offsets). 


4. Use based variables to redefine the interrretation of a 
Particular area of storage. 


5. Use the "refer" option to implement self-definins data. 


&. Manipulate areas. 
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CHARACTERISTICS OF 'based' STORAGE 


@ ADVANCED AND POWERFUL STORAGE MANAGEMENT TECHNIQUE HAVING THREE MAJOR 
APPLICATIONS 


] EXPLICITLY ALLOCATING AND FREEING SPACE MUCH LIKE CONTROLLED STORAGE 


9 EQUIVALENCING TO OR OVERLAYING A TEMPLATE UPON THE STORAGE GENERATED 
FOR SOME OTHER VARIABLE, MUCH LIKE DEFINED STORAGE 


I ACCESSING A SEGMENT IN THE VIRTUAL MEMORY DIRECTLY, THUS ENABLING 
I/O TO A SEGMENT WITHOUT USING I/O STATEMENTS 


@® THE SCOPE OF A 'based' VARIABLE IS ALWAYS ‘internal! 


THE DECLARATION OF A ‘based’ VARIABLE DESIGNATES ONLY THE DATA TYPE 
AND STORAGE TYPE ATTRIBUTE VALUES FOR THAT VARIABLE 


] IT DOES NOT DESIGNATE THE LOCATION OF THE VARIABLE 


] HENCE, EVERY REFERENCE TO A 'based' VARIABLE MUST BE QUALIFIED 
WITH A LOCATOR VALUE 


] LOCATOR VALUES CAN BE 'pointer' OR '‘offset' VALUES 
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THE 'based' ATTRIBUTE 


@ <A 'based' VARIABLE IS DECLARED WITH THE KEYWORD 'based' OPTIONALLY 
FOLLOWED BY A PARENTHESIZED LOCATOR VARIABLE 


— del x fixed bin based; 


d EVERY REFERENCE TO 'x' MUST BE QUALIFIED BY A LOCATOR VARIABLE 


1 del x fixed bin based(p); 
del p pointer; 


1 THE LOCATOR VARIABLE 'p' IS IMPLICITLY ASSOCIATED WITH 'x'! 


0 EXPLICIT LOCATOR QUALIFICATION IS NOT NECESSARY (BUT IS 
RECOMMENDED) 


@ EVERY '‘based' VARIABLE REFERENCE MUST BE QUALIFIED BY A LOCATOR 
VALUE, EITHER: 


f EXPLICITLY (USING THE => OPERATOR) 


fl OR IMPLICITLY (IF THE VARIABLE WAS DECLARED WITH THE 'based(locref)' 
ATTRIBUTE) 
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THE 'based' ATTRIBUTE 


| EXAMPLE (EXPLICITLY QUALIFIED) 


del A dec(5,2) based init(0); 
del p pointer; 
del sysprint file;. 


allocate A set(p); 


p=->A = 5; 


put list (p->A); 


free p->A; 


2 EXAMPLE (IMPLICITLY QUALIFIED) 


| del n fixed bin; | 
dal @ ahanrf ni \ b ‘e 


NS ae ws «= AGES LIT FS 
del beta pointer; 
n= 4; 

allocate 8; 


S = "abedef"; 
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EXPLICITLY ALLOCATED 'based' VARIABLES 


@ JUST AS IN THE CASE OF 'controlled' VARIABLES, BASED VARIABLES MAY 
BE EXPLICITLY ALLOCATED AND FREED 


> THE ‘allocate’ AND 'free' ARE USED 


@ 'based' VARIABLES MAY BE ALLOCATED IN TWO DIFFERENT WAYS: 
] USING THE 'in (area_name)' OPTION 
1 ALLOCATED IN THE ‘area' SPECIFIED (ONLY 'based' VARIABLES MAY 


BE ALLOCATED IN AN ‘area') 


) OMITTING THIS OPTION 


] ALLOCATED IN USER FREE AREA WITHIN [pd]>[(unique].area.linker 
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EXPLICITLY ALLOCATED 'based' VARIABLES 
THE ‘allocate’ AND 'free' STATEMENTS - 


@ THE ‘allocate' AND 'free' STATEMENTS HAVE THE FOLLOWING FORM WHEN 
USED FOR 'based' VARIABLES: 


J] allocate id [set(locref)] [in(arearef)]; 


1 WHERE 
J] id IS THE NAME OF THE 'based' VARIABLE 
1 set(locref) IS USED TO DESIGNATE THE LOCATOR VARIABLE locref 
AS THE "ADDRESS" OF THE BEGINNING OF STORAGE GENERATED FOR 
THE "based' VARIABLE id; 


J] MAY BE OMITTED IF THE VARIABLE id WAS DECLARED WITH THE 
'"pased(locref)' ATTRIBUTE 


f locref MUST SPECIFY A pointer OR offset 
J} in(arearef) SPECIFIES THE 'area' IN WHICH id IS TO BE ALLOCATED 
1 MAY BE OMITTED 


] free id [in(arearef)]; 


1 WHERE 
I id IS THE 'based' VARIABLE TO BE FREED AND MIGHT HAVE TO 


BE PTR QUALIFIED 


1 inC€arearef) IS USED IF THE VARIABLE id WAS ALLOCATED IN 
THE 'area' arearef (AND IS. OTHERWISE OMITTED) 


l NOTE: POINTER IS NULLED AFTER 'based' VARIABLE IS FREED 
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EXPLICITLY ALLOCATED 'based' VARIABLES 
.THE ‘allocate' AND '‘free' STATEMENTS 


@ EXAMPLE 


Pil: proc; 


del a(5,2) fixed based; 

del ec char(40) based(p1); 

dcl AREA area; /* INTERNAL AUTOMATIC, BY DEFAULT -*/ 
del (p1,p2) pointer; 

del sysprint file; 


allocate a set(p2); 
p2 => a= QO; 
allocate c in( AREA); 
c = "abedefg"; 


put skip(2) data(p2 -> a); 
free p2 => a, c in( AREA); 
end Pi; 
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EXPLICITLY ALLOCATED 'based' VARIABLES 
‘area' DATA TYPES 


@ THE PL/I DATA TYPE ‘area' PROVIDES A POWERFUL FACILITY FOR STORAGE 
MANAGEMENT 


@ BENEFITS OF ‘area’ MANAGEMENT 


1 OPTIONS LIKE ZERO_ON_FREEING, ZERO_ON_ALLOCATING, AND 
EXTENSIBILITY . 


1 ENABLES THE USE OF PL/1 OFFSETS 


] EASY FREEING WITH ‘empty' BUILTIN 


@ AN ‘area' VARIABLE IS USED BY THE PROGRAMMER AS A MANAGED "POOL" OF 
FREE STORAGE, TO HOLD 'based' VARIABLES 
@ THE MAXIMUM SIZE OF A NON-EXTENSIBLE ‘area’ IS 256K WORDS 


1 THE CAPACITY IS ALWAYS SOMEWHAT LESS THAN THIS 


I THE "OCCUPATION RECORD" WHICH RESIDES AT THE BEGINNING OF AN 
"area' CATALOGS THE USAGE OF SPACE IN THE ‘area! 


0 "ALLOCATION RECORDS" PRECEDE EACH BLOCK OF ALLOCATED STORAGE 
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EXPLICITLY ALLOCATED 'based' VARIABLES 
CREATING PL/I AREAS 


@ AN ‘area’ MAY BE CREATED IN THREE WAYS: 


1 BY THE 'declare' STATEMENT (del A area(area size);) 


area size SPECIFIES THE NUMBER OF WORDS TO BE ALLOCATED FOR 
THE 'area' VARIABLE 'A' (THE DEFAULT IS 1024 WORDS) 


THE LOCATION OF THE 'area' IS DETERMINED IN THE NORMAL FASHION, 
BY THE EVALUATION OF THE STORAGE CLASS ATTRIBUTE 


1 POSSIBLE ATTRIBUTES ARE static, automatic, internal, 
external, controlled AND based 


1 del A area; 
/* automatic - 'A' WOULD BE ALLOCATED ON THE STACK #*/ 


0 del B area based (get _system_free area _()); 
del get_system_free_area_ entry returns (ptr); 


/* 'B' WOULD BE ALLOCATED IN "SYSTEM FREE STORAGE" */ 
THE ‘define _area_' SUBROUTINE 
THE CALLER SPECIFIES THE LOCATION OF THE ‘area’ BY SUPPLYING 
A POINTER TO A SEGMENT IN WHICH THE ‘area’ IS TO BE ALLOCATED 


] call define _area_ (info ptr, code); 


IF A NULL POINTER IS SUPPLIED, THE SYSTEM ACQUIRES A SEGMENT 
FOR THE 'area' FROM THE PROCESS DIRECTORY TEMP SEG POOL 


MUST BE USED IF A BASED AREA IS OVERLAYED UPON ARBITRARY 
STORAGE 
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EXPLICITLY ALLOCATED 'based' VARIABLES 
CREATING PL/I AREAS 


1 BY THE 'create_area' COMMAND (AG92) 


1 THE COMMAND-LEVEL INTERFACE TO ‘define area_' 
1 AT COMMAND-LEVEL: create_area area_seg -extensible 


IN PROGRAM: del area_seg$ external area; 
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EXPLICITLY ALLOCATED 'based' VARIABLES 
LOCATOR DATA TYPES 


@ LOCATORS SPECIFY THE "ADDRESS" OF AN OBJECT, AND ARE USED TO QUALIFY 
"based' VARIABLE REFERENCES 


@ TWO TYPES OF ‘locator' VARIABLES: 


1 ‘'pointer' 
0 CONTAINS THE ABSOLUTE ADDRESS OF A BIT IN THE VIRTUAL MEMORY 


1 MAY BE ALIGNED OR UNALIGNED 
J AN ALIGNED POINTER (DEFAULT) 

‘| IS DOUBLE WORD ALIGNED 

1 IS A PAIR OF WORDS CONTAINING: 
15-BIT SEGMENT NUMBER 
3-BIT RING NUMBER 
6-BIT TAG FIELD CONTAINING OCTAL 43 
18-BIT WORD OFFSET 
6-BIT BIT OFFSET 

1 IS DECLARED 
del my pointer pointer; 


] IS SOMETIMES REFERRED TO AS AN ITS (INDIRECT TO SEGMENT) 
PAIR 
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EXPLICITLY ALLOCATED 'based' VARIABLES 
LOCATOR DATA TYPES | 


) AN UNALIGNED POINTER 
1 IS BIT ALIGNED 
1 IS A SINGLE WORD CONTAINING 
6=-BIT BIT OFFSET 
12-BIT SEGMENT NUMBER 
18=BIT WORD OFFSET 
I IS DECLARED 
del my_pointer unal ptr; 
1 IS SOMETIMES REFERRED TO AS A PACKED POINTER 
I IS HANDLED BY SPECIAL HARDWARE INSTRUCTIONS 


1 SINCE ONE OF THE COMPONENTS OF A 'pointer' IS THE SEGMENT 
NUMBER, THE 'pointer’ VALUE IS INVALID ACROSS PROCESS BOUNDARIES 
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EXPLICITLY ALLOCATED 'based' VARIABLES 
LOCATOR DATA TYPES 


) ‘'offset' 


0 AN ADDRESS TO A BIT IN AN '‘area', RELATIVE TO THE BASE OF 
THAT ‘area’ 


1 COMPOSED OF A 18 BIT WORD OFFSET AND A 6~BIT BIT OFFSET 


1 AN ‘'offset' DECLARATION MUST BE QUALIFIED BY THE NAME OF THE 
‘area' INTO WHICH THE ‘offset' REFERS IF IT IS TO BE USED IN 
A 'based' VARIABLE REFERENCE 


1 AN ‘'offset' IS VALID ACROSS PROCESS BOUNDARIES, SINCE IT DOES 
NOT REFER! TO A SEGMENT NUMBER 


] THE PL/I ‘offset' ATTRIBUTE IS USED TO DECLARE AN ‘offset! 
VARIABLE 
1 del offi offset; 


] del off2 offset(A); WHERE 'A't HAS BEEN DECLARED AN ‘area! 
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EXPLICITLY ALLOCATED 'based' VARIABLES 


LOCATOR DATA TYPES 


@ EXAMPLE USING POINTERS AND OFFSETS 


based prog: proc; 


del 
del 
del 
del 
del 
del 


sysprint file; 

A area; /* DEFAULT SIZE IS 1024 WORDS 
x fixed bin based; 

e char (8) based; 


Pp ptr; 
o offset( A); 


allocate x set (0) in (A); 

Oo -> x = 15; 

allocate ec set (p); 

Pp => c = “abcdefgh"; 

put skip data (0 => x, p => ¢); 
free o => x in (A); 

free p => oc; 


end based_prog; 


1 RESULT OF RUNNING ABOVE EXAMPLE 


! based_prog 


X= 


15 c="abedefgh"; 
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EXPLICITLY ALLOCATED 'based' VARIABLES 
LOCATOR 'builtin' FUNCTIONS 


@ PL/I BUILTIN FUNCTIONS (AM83) ARE PROVIDED TO CONVERT BETWEEN 'pointer' 
AND 'offset' LOCATOR DATA TYPES: 


1 THE 'pointer' BUILTIN FUNCTION 
I CONVERTS AN ‘'offset' IN AN 'areat INTO A 'pointer' 
0 pointer(X,A) 
ptr(X, A) 
0 RETURNS A POINTER POINTING TO 'offset' 'X' IN ‘area' 'A' 


0 THE 'offset' BUILTIN FUNCTION 


1 CONVERTS A 'pointer' WHICH POINTS TO A LOCATION IN AN '‘area' 
INTO THE ‘offset! OF THAT LOCATION IN THE ‘area’ 


0 offset(P,A) 


0 RETURNS AN '‘offset' TO THE '‘'based' VARIABLE LOCATED BY 
'pointer' 'P' IN ‘tarea' ‘At 
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EXPLICITLY ALLOCATED 'based' VARIABLES 
LOCATOR 'builtin' FUNCTIONS 


@ ADDITIONAL BUILTIN FUNCTIONS FOR THE MANIPULATION OF ‘locator' AND 
'‘area' VARIABLES: 


1 THE 'null' BUILTIN FUNCTION 


I RETURNS THE VALUE OF THE NULL POINTER, THAT IS, A POINTER TO 
SEGMENT NUMBER -1 WITH WORD OFFSET 1 


I IS USED TO TEST THE VALIDITY OF ‘pointer’ VALUES OR TO INITIALIZE 
THEM | 


] NOTE THAT A 'pointer' VARIABLE CAN BE IN ONE OF THREE STATES: 


UNDEFINED = NO VALUE HAS BEEN ASSIGNED, AND IF USED, 
'fault_tag=1' CONDITION IS USUALLY SIGNALLED 


NULL - THE ‘null' BUILTIN HAS BEEN USED TO INITIALIZE THE 
'pointer' - AN ATTEMPT TO USE SUCH A ‘pointer’ USUALLY 
RESULTS IN THE SIGNALLING OF THE 'null_pointer' CONDITION 


NON-NULL - A LEGITIMATE ADDRESS HAS BEEN ASSIGNED 


1 THE 'nullo' BUILTIN FUNCTION 


1 IS USED TO TEST THE VALIDITY OF 'offset' VALUES AND TO INITIALIZE 
THEM 


1 A NULL OFFSET IS ALL "ONES" 
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EXPLICITLY ALLOCATED 'based' VARIABLES 
LOCATOR 'builtin' FUNCTIONS 


) THE ‘addr' BUILTIN FUNCTION 
= 
I RETURNS THE ADDRESS OF ITS ARGUMENT AS A 'pointer' VALUE 


I addr(x) RETURNS A ‘'pointer' WHICH LOCATES THE GENERATION OF 
STORAGE FOR 'x! 


1 THE gapty' BUILTIN FUNCTION 
1 RETURNS THE "EMPTY" OR "NULL" VALUE OF DATA TYPE ‘area!’ 


J IS USED TO DETERMINE IF AN ‘area't IS EMPTY AND IS ALSO USED 
TO INITIALIZE AN ‘area' 


J <A "QUICK AND DIRTY" FREEING MECHANISM 


1 THE NONSTANDARD 'pointer' BUILTIN FUNCTION 


1 RETURNS A 'pointer' VALUE GIVEN A 'pointer' POINTING ANYWHERE 
IN A SEGMENT AND A WORD OFFSET EXPRESSED AS AN ARITHMETIC OR 
BIT STRING VALUE 


1 pointer(P,N) OR ptr(P,N) RETURNS A ‘'pointer' TO THE Nth WORD 
OF THE SEGMENT 


] IS DISTINGUISHED FROM THE STANDARD ‘pointer' BUILTIN FUNCTION 
BY THE DATA TYPE OF THE ARGUMENTS 
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EXPLICITLY ALLOCATED 'based' VARIABLES 
LOCATOR 'builtin' FUNCTIONS 


f THE NONSTANDARD ‘taddrel' BUILTIN FUNCTION 
1 RETURNS A 'pointer' TO A WORD RELATIVE TO ANOTHER POINTER 
1 addrel (P,N) POINTS TO A WORD N WORDS AWAY FROM P 


1 THE RESULTING POINTER HAS A O BIT OFFSET, REGARDLESS OF 
P'S BIT OFFSET 


1 N IS AS IN THE ABOVE NONSTANDARD pointer BUILTIN 
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EXPLICITLY ALLOCATED 'based' VARIABLES 
USING EXPLICITLY ALLOCATED 'based' STORAGE 


@ EXPLICITLY ALLOCATED 'based' STORAGE IS GENERALLY USED FOR ONE OF 
THREE PURPOSES: 


I TO DIRECTLY CONTROL THE ALLOCATION AND FREEING OF STORAGE 


1 TO PROVIDE STORAGE FOR DATA ITEMS WHOSE EXTENTS ARE NOT KNOWN AT 
COMPILE TIME 


[I TO TAKE ADVANTAGE OF CERTAIN FEATURES MADE AVAILABLE THROUGH THE 
USE OF ‘tarea' VARIABLES 


1 ZERO ON ALLOCATION 
1 ZERO ON FREEING 
f MASS FREEING OF ALLOCATED VARIABLES 


] EXTENSIBILITY OF AREAS 
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EXPLICITLY ALLOCATED 'based' VARIABLES 
USING EXPLICITLY ALLOCATED 'based' STORAGE 


@ EXPLICITLY ALLOCATED 'based' VARIABLES CAN BE USED TO PROVIDE STORAGE 
FOR DATA ITEMS WHOSE EXTENTS ARE NOT KNOWN AT COMPILE TIME 


I ADJUSTABLE EXTENTS ARE ARRAY BOUNDS, MAXIMUM STRING LENGTHS, AND 
‘area' SIZES 


1 UNLIKE 'controlled' VARIABLES, FOR 'based' VARIABLES, THE VALUES 
OF VARIABLE EXTENTS ARE COMPUTED FOR EACH REFERENCE 


0 THAT IS, THE ADJUSTED EXTENTS ARE NOT SAVED WHEN THE VARIABLE 
IS FIRST ALLOCATED 


] IT IS THE RESPONSIBILITY OF THE PROGRAM TO PRESERVE SUCH EXTENTS 
TO AVOID VIOLATING THE PL/I CONSISTENCY RULES 
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EXPLICITLY ALLOCATED 'based' VARIABLES 
USING EXPLICITLY ALLOCATED 'based' STORAGE 


J) EXAMPLE OF AN INVALID PROGRAM 


Pi: proc; 


del n fixed bin; 
del S char(n+2) based( beta); 
del beta pointer; 


n = 4: 


allocate S; 


—Jn'= "100; 
S 


= "abcdef"; 


free S; 
end; 


0 THIS PROGRAM IS INVALID 


I WHEN THE ‘'based' VARIABLE 'S' IS ALLOCATED, IT IS GIVEN 6 
BYTES OF STORAGE 


] WHEN IT IS REFERENCED IN THE ASSIGNMENT STATEMENT, THE 
EXTENTS ARE RECOMPUTED TO 102, AND THE STRING "“abedef" 
WILL BE PADDED TO A LENGTH OF 102 BEFORE BEING ASSIGNED 
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EXPLICITLY ALLOCATED 'based' VARIABLES 
THE ‘refer' QPTION 


@ SINCE THE VARIABLE EXTENTS OF 'based' VARIABLES ARE NOT SAVED BY 
PL/I, A SPECIAL FEATURE, THE 'refer' OPTION IS PROVIDED 


1 IT IS USED TO SAVE THE VALUE CALCULATED FOR VARIABLE EXTENTS OF 
A 'based' VARIABLE WHEN IT IS ALLOCATED 


] IT IS USED WITHIN A STRUCTURE VARIABLE TO CREATE A "SELF-DEFINING 
STRUCTURE”, WHICH CARRIES ITS OWN EXTENTS 


Not To Be Reproduced 3-21 F15C 


EXPLICITLY ALLOCATED 'based' VARIABLES 


THE 'refer' OPTION 


A VALID EXAMPLE 


P3: proc; 


del n fixed bin; 
del 1 Spair based(beta), 

2n2 fixed bin, 

2 S char(n+2 refer(n2)); 
del beta ptr; 


ae 

allocate Spair; 

n = 100; 

Spair.S = "“abedef"; 
free Spair; 


33 


NOTE: A PARENTHESIZED REFERENCE FOLLOWING THE KEYWORD '‘'refer' 
MUST DESIGNATE A SCALAR MEMBER DEFINED EARLIER IN THE SAME STRUCTURE 


AT ALLOCATION TIME, ANY INITIAL EXTENT EXPRESSION IS EVALUATED, 
AND IS .SAVED IN THE MEMBER REFERENCED BY THE '‘refer' OPTION 
CLAUSE 


ON SUBSEQUENT REFERENCES TO THE 'based' ADJUSTABLE VARIABLE, THE 
EXTENT IS DETERMINED BY REFERRING TO THE MEMBER 
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EXPLICITLY ALLOCATED 'based' VARIABLES 
USING ‘area' VARIABLES 


@ EXPLICITLY ALLOCATED 'based' VARIABLES MAY BE USED TO TAKE ADVANTAGE 
OF THE STORAGE MANAGEMENT FACILITIES OFFERED BY THE. PL/I ‘area’ 
VARIABLES 


@ NOTE THAT THE ONLY TYPE OF VARIABLE WHICH MAY BE ALLOCATED IN AN 
‘area’ IS AN EXPLICITLY ALLOCATED 'based' VARIABLE 


@ NOTE ALSO THAT PL/1 ‘'offset' VALUES CAN ONLY LOCATE STORAGE WITHIN 
AREAS 
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EQUIVALENCED "based' STORAGE 


@® THE USE OF EQUIVALENCED 'based' VARIABLES IS ONE OF THE MOST POWERFUL 
STORAGE MANAGEMENT CAPABILITIES OFFERED BY PL/I 


@ UNLIKE EXPLICITLY ALLOCATED 'based' VARIABLES, AN EQUIVALENCED 'based' 
VARIABLE: 


1 IS SUPERIMPOSED ON OR EQUIVALENCED TO A PREVIOUSLY ALLOCATED 
"BASE" VARIABLE 


1 NEVER HAS STORAGE OF ITS OWN, AND THUS IS NEVER ALLOCATED OR 
FREED 


@ THE LOCATOR VALUE USED TO REFERENCE THE BASE VARIABLE iS OBTAINED 
BY THE ‘'addr' BUILTIN FUNCTION 


@ EXAMPLE 


del a fixed bin (35); 
del b fixed bin (35) based (addr(a)); 


53 


23 
skip list (a,b); 
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EQUIVALENCED 'based' STORAGE 


@ ADDITIONAL EXAMPLES (NOTE: FOR THESE EXAMPLES, THE DATA TYPE OF 
THE 'based' VARIABLE IS THE SAME AS THAT OF THE BASE VARIABLE) 


0 EXAMPLE 1 
Pil: proc; 
del x fixed dec(5,2); 
dcl y fixed dec(5,2) based; 
dcl p ptr; 
del (sysin,sysprint) file; 
p = addr(x); 
get list(x); 
put skip list(2 * p->y); 
Pas 
) EXAMPLE 2 


1, AC5D:, 
2 x fixed bin, 
2 y char(6); 
del 1 B based, 
2r fixed bin, 
2s char(6); 
del p ptr; 


p = addr(A(3)); 
Pp -> B.s = "third": 
/* SETS AC3).y TO "third" */ 
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EQUIVALENCED 'based' STORAGE 


# IT IS ALSO POSSIBLE FOR THE DATA TYPES OF THE 'based' AND BASE 
VARIABLE TO DIFFER 


] EXAMPLE 1 


del x fixed bin(35); 
del y bit(36) based (addr(x)); 


% 2°53 
put skip list (x,y); 


1 EXAMPLE 2 


del number(1024) float bin; 
del 1 float num based, 
2 sign bit(1) unal, 
2 exponent bit(7) unal, 
2 m_sign bit(1) unal, 
2 mantissa bit(27) unal; 


" addr( number(43)); 


l p -> float_num MEANS number(43) 
0 p => sign MEANS bit O of number(43) 


1 p-> mantissa MEANS bits 9-35 of number(43) 
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EQUIVALENCED 'based' STORAGE 


del x _— char(8) varying init(“ ABC’); 


de! 1 y based (addr(x)), 
2 length fixed bin (35), 


2 actual_string char (8); 


oe ME) DE EVAVAVAVAA 


length 


x = “BONJOUR”: 
if y.jength = 7 
then put list (y.actual_ string); 
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AN APPLICATION FOR 'based' VARIABLES 


LINKED INFORMATION STRUCTURES 


# EQUIVALENCED 'based' STRUCTURES CAN BE USED TO PROVIDE STORAGE FOR 
DATA ITEMS WHICH HAVE BEEN ORGANIZED INTO AN ARBITRARILY LINKED 
INFORMATION NETWORK 


] SINGLY AND DOUBLY LINKED LISTS 
{ TERMINATING LISTS 


1 CIRCULAR LISTS 
1 TREES AND OTHER DIRECTED GRAPHS 


1 OTHER INFORMATION NETWORKS 


@ IT SHOULD BE NOTED THAT SUCH STRUCTURES ARE HEAVILY USED IN THE 
SUPERVISOR, AND THAT MOST OF THE SUPERVISOR DATABASES ARE 'based' 
STRUCTURES DEFINED IN "INCLUDE FILES" SUBORDINATE TO >ldd>include 
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AN APPLICATION FOR 'based' VARIABLES 


LINKED INFORMATION STRUCTURES 


@ AN EXAMPLE (from stack_frame.incl.pl1) 


del 1 stack frame based(sp) aligned, 

pointer _registers(0 : 7) ptr, 

prev_sp pointer, /* points to previous stack frame */ 
next_ , sp pointer, /* points to next stack frame */ 
return |_ptr pointer, 

entry ‘ptr pointer, 

operator_ and lp _ptr ptr, 

arg ptr pointer, 

static _ptr Pee unaligned, 

support - ‘ptr ptr unaligned, 

on_unit_relp1 bit(18) unaligned, 

on_unit relp2 bit(18) unaligned, 
translator_id bit(18) unaligned, 
operator_ return_ offset bit(18) unaligned, 
x(0: 7) bit(18) unaligned, 

a bit(36), 

q bit(36), 

e bit(36), 

timer bit(27) unaligned, 

pad bit(6) unaligned, 

ring alarm_reg bit(3) unaligned; 


MNMMMMNMMPNMNNNND WYMNNND Pl 


# THERE ARE OVER 2000 SUCH INCLUDE FILES IN >ldd>inelude (TOPIC 5 
DEMONSTRATES THEIR USAGE) 


YOU ARE NOW READY FOR WORKSHOP 
#2 
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TOPIC IV 


Introduction to Multics Subroutines 
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Topic IV INTRODUCTION TO MULTICS SUBROUTINES Toric IV 
OBJECTIVES: 

Upon completion of tis topic, students should be able to: 

1. Give reasons for havins a set of Multics subroutines. 


2. Give general g3uidelines for use af Multics system 
subroutines. 


Se List some of the conventions followed when usins Multics 
system subroutines. 
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WHAT ARE SYSTEM SUBROUTINES? 


@® SYSTEM SUBROUTINES ARE CALLABLE PROCEDURES USED BY THE MULTICS 
OPERATING SYSTEM 


I] THEY ARE THE SUBROUTINES THAT THE PROGRAMMER USES TO PERFORM 
COMMAND LEVEL LIKE FUNCTIONS 


] THEY ARE THE PROCEDURES ACTUALLY CALLED BY COMMAND PROCEDURES 
(EXAMPLE: THE delete COMMAND PROCEDURE CALLS THE delete_ 
SUBROUTINE) 


0 SOME SUBROUTINES HAVE A ONE-TO-ONE RELATION WITH MULTICS COMMANDS 
(EXAMPLE: send_message_ SUBROUTINE PERFORMS THE send_message 
COMMAND FUNCTION FROM WITHIN A PROGRAM) 


0 OTHER SUBROUTINES PERFORM ONLY A SMALL PART OF WHAT AN ENTIRE 
COMMAND DOES. EXAMPLES: 
J iox_ SUBROUTINES ARE USED BY SEVERAL COMMANDS 


‘| convert _date_to_binary IS JUST ONE OF MANY SUBROUTINES 
CALLED BY THE enter_ abs s request AND memo COMMANDS: 
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SYSTEM SUBROUTINE CONVENTIONS 


SYSTEM SUBROUTINE ENTRY NAMES END IN AN UNDERSCORE (_) 
MANY SUBROUTINES HAVE SEVERAL ENTRY POINTS 
1 hes $list_acl 


hes $make_seg 


hes $status_ 


THEY ARE DOCUMENTED IN MULTICS SUBROUTINES & I/O MODULES (AG93) 


THEY ARE LOCATED PRIMARILY IN >system_library standard AND 
>system_library 1 


THEY ARE WRITTEN IN PL/T OR ALM 
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USING SYSTEM SUBROUTINES 


@ SINCE THEY ARE EXTERNAL SUBROUTINES, EACH MUST BE DECLARED IN THE 
USER'S PROGRAM AS ‘external entry' 


1 THE DATA TYPES FOR THE PARAMETER LIST CAN BE FOUND IN THE MANUAL 
DESCRIPTION OF THE SUBROUTINE 


f IF THEY ACCEPT A VARIABLE NUMBER OF ARGUMENTS, THEY ARE DECLARED 
‘entry options (variable)' 


@ SEVERAL MAKE USE OF STRUCTURES TO PASS DATA TO AND FROM THE CALLING 
PROCEDUKE 


] IN THIS CASE, ONE OF THE ARGUMENTS PASSED TO THE PROCEDURE IS A 
POINTER TO THAT STRUCTURE 


[ THE DECLARATIONS REQUIRED FOR THESE STRUCTURES ARE FOUND IN THE 
DOCUMENTATION FOR THE SUBROUTINE 


] THE DECLARATIONS OF SOME OF THESE STRUCTURES ARE FOUND IN INCLUDE 
FILES IN >ldd>include 


] EXAMPLE: hes $status_ 


f THIS SUBROUTINE IS PASSED A. POINTER TO A STRUCTURE INTO WHICH 
IT IS TO PUT ITS INFORMATION 


T A DECLARATION FOR THAT STRUCTURE IS FOUND IN 
>1dd>include>status_structures.incl.pl1 (FURTHER DISCUSSED IN 
TOPIC 10) 
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STATUS CODES 


® ONE OF THE OUTPUT ARGUMENTS OF A SUBROUTINE IS USUALLY A ‘status 
code! 


9 THE ‘status code' IS THE MEANS BY WHICH THE CALLED PROCEDURE MAY 
REPORT ANY UNUSUAL OCCURRENCE TO ITS IMMEDIATE CALLER 


1 THE VARIABLE THAT RECEIVES THE ‘status code' MUST BE DECLARED 
"fixed bin(35)' 


0 IF THE SUBROUTINE RUNS TO COMPLETION WITH ABSOLUTELY NO ABNORMAL 
CONDITIONS TO REPORT, THE STATUS CODE IS 0 (ZERO) 


® com_err_ 
1 USED TO REPORT ERRORS FROM WITHIN A PROGRAM 


1 TYPICAL USAGE 


del com_err entry options (variable); 
del code fixed bin(35); 
call hes $status ~(......-e0.5050-,00de) ; 
if code “= 0 
then do3;. 

cali com_err_ (code, *gamma"™); 

return; aac 

end; 


I IF AN ERROR OCCURRED, IT MIGHT PRINT SOMETHING LIKE: 


gamma: Incorrect access to directory containing... 


SOME NON-ZERO STATUS CODES DO NOT INDICATE AN ERROR 
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STATUS CODES 


J STATUS CODES AND THEIR MEANINGS ARE LISTED IN CHAPTER 7 OF THE 
MULTICS PROGRAMMER'S REFERENCE GUIDE (AG91) 


0 THE STANDARD STATUS CODES AND THEIR CORRESPONDING MESSAGES ARE 
IN A SEGMENT CALLED error table _, WHICH IS IN >sl1 


1 IT IS POSSIBLE TO TEST FOR A PARTICULAR STATUS CODE VALUE USING 
THE SYMBOLIC REPRESENTATION 


del error_table $segknown external fixed bin(35); 
if code = error table $segknown 
then do; 
call com_err_ (code, "beta"); 
goto try again; 
end; 
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STATUS CODES 


1 THE probe 'display' REQUEST CAN BE USED TO DISPLAY THE ERROR 
MESSAGE ASSOCIATED WITH A STATUS CODE 


segknown: proc; 


del initiate file_ entry (char(*), char(*), bit(*), ptr, 
fixed bin(24), fixed bin(35)); 


del seg ptr pointer; 
del bit count fixed bin (24); 
del code fixed bin (35); 
del null builtin; 


call initiate file (">udd>MED>jcej>15¢e", "foo", "101"b, seg ptr, 
bit_count, code); 


end /* segknown */; 


r 11:41 0.100 3 


! seg known 
Stopped after line 10 of segknown. (level 5) 
! se 
call initiate file (">udd>MED>jcej>15c¢e", "foo", "101"b, seg ptr 
bit count, code); 
! v seg ptr 
seg ptr = null 
! v code . 
code = 8589679427 
! display code code 
error _ table $noentry “Entry not found." 


q 
r 11:42 0.733 86 
! ls foo 


list: foo not found 
ro11:42 0.212 11 


Not To Be Reproduced . 46 F15C 
| (End Of Topic) 


TOPIC V 


Advanced Based Variable Usage 


Gaining Direct Access to Segments. . 
MOCIVARLION. 6. a ce eS eH 
Obtaining a Pointer to a Segment 
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Toric V ADVANCED BASED VARIABLE USAGE Toric V 
OBJECTIVES: 
Upon completion of this toric, students should be able to: 


1. Use Multics subroutines to manipulate sesments directly 
instead of using PL/1 I/O statements. 


2. Manipulate archive components using Multics subroutines. 


3. Examine some system databases usins based structures and 
Multics subroutines. 
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GAINING DIRECT ACCESS TO SEGMENTS 


MOTIVATION 


® EQUIVALENCED BASED VARIABLES CAN BE USED TO GAIN DIRECT ACCESS TO 
SEGMENTS IN THE VIRTUAL MEMORY 


I IN THIS WAY, AN ENTIRE DATA SEGMENT CAN BE ACCESSED WITHOUT 
RESORTING TO LANGUAGE I/0 


IT ONE MUST OBTAIN A '‘'pointer' TO THE SEGMENT IN ORDER TO GAIN 
DIRECT ACCESS TO IT ; 


[ THE FOLLOWING PAGES SHOW SUBROUTINES THAT RETURN A POINTER TO A 
SEGMENT 
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GAINING DIRECT ACCESS TO SEGMENTS 


@ MULTICS SUBROUTINES WHICH OBTAIN A 'pointer' TO A SEGMENT: 


I hes $make_seg 


) BASIC FUNCTIONS 
1 SEGMENT CREATION IF IT DOES NOT EXIST 
I SEGMENT INITIATION 


1 USAGE 


del hes $make_seg entry 


(char(*), /* INPUT */ 

char(*), /* INPUT #/ 

char(*), /* INPUT #*/ 

fixed bin(5), /#* INPUT */ 

- ptr, = /* QUTPUT */ 
fixed bin(35)); /*® QUTPUT #*/ 
call hes _$make_seg 

(dir_name, /* PATH OF CONTAINING DIR’ #/ 
entr yname, /* SEGMENT NAME #/ oe 
ref_name, /* DESIRED REFERENCE NAME */ = 
‘mode, /* ACCESS FOR THIS USER */ 
seg ptr, /* POINTS TO CREATED/FOUND SEG #/ 
code); /* STATUS CODE */ 
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GAINING DIRECT ACCESS TO SEGMENTS 


) NOTES 


I IF SEGMENT DOESN'T EXIST, APPEND PERMISSION REQUIRED ON 
CONTAINING DIRECTORY 


MAKING-KNOWN REQUIRES NONNULL ACCESS ON SEGMENT 

IF entryname IS NULL, UNIQUE SEGNAME IS GENERATED 

IF dir_name IS NULL, SEGMENT IS CREATED IN PROCESS DIRECTORY 
ref name USUALLY NULL 


ee — ee —— ee a | 


mode ENCODES THUSLY 

READ => 01000b 

EXECUTE -> 00100b 

WRITE => 00010b 
l seg ptr IS RETURNED NULL IF REAL TROUBLE WAS ENCOUNTERED 
1 code MIGHT BE NON-ZERO UNDER 'NORMAL' CIRCUMSTANCES: 


error table $namedup 
error table $segknown 
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GAINING DIRECT ACCESS TO SEGMENTS 


OBTAINING A POINTER TO A SEGMENT 


1 IF THE PROGRAMMER DOESN'T CARE IF THE SEGMENT ALREADY EXISTS 
OR IS ALREADY INITIATED HE RELIES ONLY ON THE NON-NULL seg_ ptr 


del hes $make_seg entry (char (*), char (*), char (*), 
fixed bin (5), ptr, fixed bin (35)); 
del com_err_ entry options (variable); 


eall “hes | $make_ Seg(..+..5.8e8_ ptr, code); 
if seg_ptr = null() 
then do; 

call com_err_ (code, "alpha"); 


end; 


J IF THE PROGRAMMER EXPECTS: TO BE CREATING A NEW SEGMENT AND 
DOES NOT WANT TO REFERENCE AN ALREADY EXISTING SEGMENT, HE 
MUST CHECK THE CODE 


del hes $make_seg entry (char (*), char (*), char (*), 
fixed bin (5), ptr, fixed bin (35)); 

del com_err_ entry options (variable); 

del error_table $namedup fixed bin(35) ext static; 

del error_ ~ table $segknown fixed bin(35) ext static; 


eall “hes $make_seg (.........8eg_ptr, code); 
if seg_ptr = null() {| code = error_tabile _$ seg known 
| code = error_ ~table_ _$named up 
then do; 
- ¢@all com_err_ (code, "alpha"); 


end; 
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GAINING DIRECT ACCESS TO SEGMENTS 


0 initiate file_ 


1 BASIC FUNCTIONS 
I MAKES A SEGMENT KNOWN WITH A NULL REFERENCE NAME 


I CHECKS THAT THE USER'S PROCESS HAS AT LEAST THE DESIRED 
ACCESS ON THE SEGMENT 


I RETURNS A POINTER TO THE SEGMENT 
] RETURNS A BIT COUNT 


I USAGE 
del initiate file_ entry 
(char(*), ; /* INPUT */ 
char(*), /* INPUT */ 
bit(*), /* INPUT */ 
pointer, /* OUTPUT #*/ 


fixed binary (24), /*® QUTPUT */ 
fixed binary (35)); /* OUTPUT */ 


call initiate file_ 


(dirname, /* PATH OF CONTAINING DIR */ 
entr yname, /* SEGMENT NAME */ 

mode, /* REQUIRED ACCESS MODE */ 
seg _ptr, /* POINTS TO INITIATED SEG #/ 
bit_count, /* BIT COUNT OF SEGMENT #*/ 


code); /* STANDARD SYSTEM CODE */ 
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GAINING DIRECT ACCESS TO SEGMENTS 


OBTAINING A POINTER TO A SEGMENT 


1 NOTES 
I THE SEGMENT MUST EXIST 


] MAKING-KNOWN REQUIRES NONNULL ACCESS ON THE SEGMENT, AS 
WELL AS THE REQUIRED MODES SPECIFIED IN THE CALL 


I mode ENCODES THUSLY 
READ -> "100"b 
EXECUTE => "010"b 
WRITE -> "001"b 


(>1dd>include>access mode values.inecl.pli CONTAINS NAMED 
CONSTANTS FOR THESE ACCESS MODES) 


1 seg_ptr IS NULL IF THE SEGMENT IS NOT MADE KNOWN 
J code IS A STANDARD STATUS CODE AND COULD BE: 
error_table $no_r_permission 


error ~ table, _$no_ ee )_ permission 
error ~ table _$no_ Ww | permission 
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GAINING DIRECT ACCESS TO SEGMENTS 


OBTAINING A POINTER TO A SEGMENT 


1 initiate file $component 


J BASIC FUNCTIONS 


] MAKES EITHER A SEGMENT OR AN ARCHIVE COMPONENT KNOWN WITH 
A NULL REFERENCE NAME 


I IF NO COMPONENT NAME IS SPECIFIED, THIS ENTRY POINT IS 
IDENTICAL TO initiate file_ 


USAGE 
del initiate file $component entry 
(char (*), /* INPUT #/ 
char (*), /* INPUT #/ 
char (*), /* INPUT */ 
bit (*), /* INPUT */ 
pointer, /* QUTPUT */ 


fixed binary (24), /* OUTPUT */ 
fixed binary (35)); /* OUTPUT #*#/ 


eall initiate_ file $component 


(dirname, /* PATH OF CONTAINING DIR *Z2 

entryname, /* NAME OF SEGMENT OR ARCHIVE */ 
component name, /* NULL OR NAME OF COMPONENT */ 

mode, /* REQUIRED ACCESS MODE */ 

component ptr, /* PTR TO SEGMENT OR COMPONENT */ 
bit_count, /* BIT COUNT OF SEGMENT OR COMPONENT */ 
code); /* STANDARD SYSTEM CODE */ 


0 NOTES 


] THE ARCHIVE COMPONENT MAY NOT BE MODIFIED (ONLY READ ACCESS 
IS PERMITTED) 


0 ONLY THE DATA STARTING AT THE POINTER AND EXTENDING AS FAR 


AS THE BIT COUNT MAY BE REFERENCED (NO DATA BEFORE OR 
AFTER THE COMPONENT MAY BE REFERENCED) 
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GAINING DIRECT ACCESS TO SEGMENTS 


OBTAINING A POINTER TO A SEGMENT 


0 TO OBTAIN A POINTER TO A COMPONENT WITHIN AN ARCHIVE SEGMENT SEE 
] archive $get_component 


0 archive $next_component 


@® NOTE THAT THE SUBROUTINES DISCUSSED REQUIRE AN ABSOLUTE DIRECTORY 
PATHNAME 


@ THE expand pathname SUBROUTINE CAN BE USED TO CONVERT A PATHNAME 
(WHETHER RELATIVE OR ABSOLUTE) INTO THE REQUIRED DIRECTORY PATHNAME 
AND ENTRYNAME STRINGS 


1 USAGE 


del expand pathname entry 
(char(¥), char(*¥), char(*), fixed bin(35)); 


call expand pathname 


(rel_path, 7* RELATIVE OR ABSOLUTE PATHNAME 
TO BE EXPANDED #*/ 
dir_name, /* RETURNED DIRECTORY PORTION OF 
PATHNAME */ 
entryname, /* RETURNED ENTRYNAME PORTION OF 
¢ PATHNAME */ 
code); 
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GAINING DIRECT ACCESS TO SEGMENTS 


AN EXAMPLE 


stack tracer: proc; 


Zinclude stack header; 
Z@include stack ._ frame; 


del com_err_ entry options (variable); 

del get _pdir_ entry () returns (char (168)); 

del initiate file | entry (char (*), char (*), bit (*), pointer, 
fixed binary (24), fixed binary (35)); 

del interpret _ptr_ entry (ptr, ptr, ptr); . 


del . bit count fixed binary (24); 
del code fixed bin (35); 
del ME char (12) static 
init ("stack_tracer") options (constant) ; 

del no frames fixed bin; 
dcl 1 owner, 

2 message char (64), 

2 segname ehar (32), 


2entryname char (33); 
del (save ptr, 3 


shp) ptr; 
del sysprint file; 
del (addr, 

ltrin, 

null) builtin; 


/* GET POINTER TO BASE OF STACK SEGMENT */ 


call initiate file (get _pdir_ (), "stack 4", "100"b, 
shp, bit cout, code); 
if shp = null () vi 
then do; 
call com_err_ (code, ME); 
return; 
end /*® then do #/; 


/* WALK FRAMES TO FIND LAST ONE */ 


no_frames = 0; 
do sp = shp -> Stack header.stack begin ptr 
repeat sp =>" stack frame. next sp 
while (sp “= shp -> stack_header.stack_end_ptr); 
save _ ptr = sp; 
no frames = no_frames + 1; 
end /¥ do sp */; 


/* NOW TRACE BACKWARDS AND DUMP #/ 
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GAINING DIRECT ACCESS TO SEGMENTS 


AN EXAMPLE 


do sp = save ptr 
repeat sp -> stack frame. prev_sp 
while (sp “= null T)); 
call interpret ptr_ (sp -> stack _frame.entry ptr, sp, 
addr (owner)); 
put skip (2) edit ("FRAME", no frames, " IS OWNED BY ", 
rtrim( owner.segname) , rtrim( owner. entr yname) ) 
(a,f(3),a,a,a); 
put skip list (" FRAME STARTS AT", Sp); 
put skip list (" ARG POINTER IS", sp -> stack frame.arg ptr); 
no frames = no_frames -1; 
end /*¥ do sp *#/; 


/* ALL DONE #*/ 

put skip (2) list ("End stack tracer"); 
put skip; 

close file (sysprint); 


end /* stack tracer */; 


r 14:08 0.237 6 


stack tracer 


FRAME 5 IS OWNED BY stack _tracer$stack th acer 


FRAME STARTS AT pointer (234 15640) 
ARG POINTER IS pointer(23415202) 
FRAME 4 IS OWNED BY command processor $command_processor_ 
FRAME STARTS AT pointer(234 |5000) 
ARG POINTER IS pointer(234 (4274) 
FRAME 3 IS OWNED BY abbrev$abbrev_ cp 
FRAME STARTS AT pointer(234 12700) 
ARG POINTER IS pointer (23412564) 
FRAME 2 IS OWNED BY listen $listen_ 
FRAME STARTS AT pointer(234;j2400) 
ARG POINTER IS pointer(234{2236) 
FRAME 1 IS OWNED BY initialize_process $initialize process_ 
FRAME STARTS AT pointer (234 (2000) 
ARG POINTER IS pointer(234{0) 


End Stack tracer 
r 14:09 0.658 46 
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GAINING DIRECT ACCESS TO SEGMENTS 


AN EXAMPLE 


YOU ARE NOW READY FOR WORKSHOP 
#3 
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(End Of Topic) 
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Topic VI MULTICS CONDITION MECHANISM Topic VI 


OBJECTIVES: 
Upon completion of this topic, students should be able to: 


1. Describe the actions taken by Multics when a condition is 
sisnalled. 


2. Write handlers for the followings conditions: 
cleanup 
Prosgramuinterrupt 
finish 


User-defined and PL/i-defined conditions 
3. Write an “any_other" handler. 


s the circumstances under which the system-defined 
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INTRODUCTION 


@ THE MULTICS CONDITION MECHANISM IS A FACILITY THAT NOTIFIES A PROGRAM 
OF AN EXCEPTIONAL CONDITION | . 


I A CONDITION IS A STATE OF THE EXECUTING PROCESS 


I A CONDITION MAY OR MAY NOT INDICATE THAT AN ERROR HAS OCCURRED 


@ IN MULTICS, THERE ARE THREE BROAD CATEGORIES OF CONDITIONS: 


J] SYSTEM-DEFINED CONDITIONS (MULTICS LEVEL) 
1 ARE DEFINED AS PART OF THE MULTICS SYSTEM 


J] ARE DETECTED BY THE MULTICS HARDWARE OR SOFTWARE 
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I EXAMPLES 
cleanup 
no_read_ permission 


out_of bounds 
record quota overflow - 


I 
0 
J quit 
q 


AND OTHERS, TO BE DISCUSSED LATER 
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INTRODUCTION 


1 LANGUAGE-DEFINED CONDITIONS 
I ARE DEFINED AS PART OF PL/I 


I ARE DETECTED AND SIGNALLED BY THE PL/I RUNTIME PROCESSOR 


I EXAMPLES 
. J] conversion 
1 endfile 
02 AND OTHERS... 
f PROGRAMMER=DEFINED CONDITIONS 


I ARE DEFINED BY THE PROGRAMMER 


fT ARE DETECTED AND SIGNALLED EX 


a) 
r* 
t+ 
Co) 
4 
3 


[TLY BY THE PROGRAMMER 


I EXAMPLES 
I oops 


0 OR WHATEVER ONE DESIRES... 
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INTRODUCTION 


@ THE MULTICS CONDITION MECHANISM IS INVOKED WHEN A CONDITION IS DETECTED 
AND SIGNALLED BY: 


] THE SYSTEM 


I EXAMPLE: zerodivide OCCURS 


I THE USER PROGRAM 


] EXAMPLE: “signal zerodivide;" 
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INTRODUCTION 


@ THE SIGNALLING OF A CONDITION: 


1 IMMEDIATELY STOPS THE PROGRAM AT THE CURRENT POINT OF EXECUTION 


1 CAUSES A BLOCK ACTIVATION OF THE MOST RECENTLY ESTABLISHED ON 
UNIT FOR THAT CONDITION 


1 THE APPROPRIATE ON UNIT IS FOUND BY MAKING A BACKWARDS TRACE 
OF THE STACK 


1 EACH BLOCK ACTIVATION ON THE STACK CAN HAVE ONLY ONE ON UNIT 
ESTABLISHED FOR EACH CONDITION AT ANY GIVEN TIME 


sub2$sube2 


G 
qi 
it 
i 
li 
t 
q 
q 


dea ON UNIT ESTABLISHED FOR zerodivide 


dea ON UNIT ESTABLISHED FOR zerodivide 


sub1$sub1 


main$main 


command processor _ 


listen_ 


initialize process_ 


USER STACK 
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INTRODUCTION 


0 IF zerodivide IS SIGNALLED IN sub2, A BLOCK IS ACTIVATED FOR THE 


ON UNIT ESTABLISHED IN sub1 


subl1$zerodivide.n 


(signal_) 


(pl1_signal_from_ops_) 


sub2$sub2 


sub1$sub1 


| main$main 


command processor_ 


abbrev 


initialize process 


USER STACK 
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[4———— ON UNIT ESTABLISHED FOR zerodivide 
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ESTABLISHING AND REVERTING CONDITION HANDLERS 


I on zerodivide begin; 


end; 
I on zerodivide system; 
I on zerodivide snap system; 
I IF THE CONDITION SPECIFIED IS SIGNALLED, THE ‘probe’ COMMAND 


IS IMMEDIATELY INVOKED BEFORE THE ‘on unit' IS INVOKED (FOR 
AN ABSENTEE PROCESS, THE ‘trace _stack' COMMAND IS EXECUTED) 


J on zerodivide call probe; 


@ THERE ARE THREE WAYS TO REVERT AN ‘on unit' 
1 PL/I ‘'revert' STATEMENT (EXAMPLE: revert zerodivide;) 
0 BLOCK DEACTIVATION CAUSED BY REACHING A BLOCK ‘'end' STATEMENT 


] NON-LOCAL 'go to' WHICH CAUSES DEACTIVATION OF OF ALL BLOCKS 
FROM THE TOP OF THE STACK TO THE PROCEDURE CONTAINING THE LABEL 
THAT IS THE TARGET OF THE ‘go to’ 
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ESTABLISHING AND REVERTING CONDITION HANDLERS 


This Page Intentionally Left Blank 


Not To Be Reproduced 6-7 F15C 


ESTABLISHING AND REVERTING CONDITION HANDLERS 


example: 
del subi external entry; 
del sub2 external entry; 
del overflow condition; 
on overflow <on unit 15; 
call sub1; 
<statement 15; 


call sub2; 
end /* example */; 


subi: proc; 


_dcl overflow condition; 


<statement 2>; 


on overflow <on unit 2); 


<statement 35; 
end /* subi #*/; 


| Sub2: proc; | 


del overflow condition; 


<statement 4); 


on overflow <on unit 3); 


revert overflow; 


<statement 6>; 
end /* sub2 #*/; 


ee | 
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<statement 5>; | 
| 


ESTABLISHING AND REVERTING CONDITION HANDLERS 


@® ASSUME THAT EACH OF THE & NUMBERED STATEMENTS IN THE 3 PROCEDURES 
ON THE PREVIOUS PAGE IS A SIMPLE ASSIGNMENT STATEMENT (THERE ARE NO 
goto's) 


FILL IN THE CHART SHOWING WHICH ‘on unit' WOULD BE INVOKED IF 'overflow' 
OCCURRED IN THE NUMBERED STATEMENT SPECIFIED 
STATEMENT CAUSING overflow 

TO BE SIGNALLED ON UNIT INVOKED 


1 


non WO &F& WW DY 
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A SPECIAL CATCH-ALL CONDITION HANDLER 


@® THE ‘any other' CONDITION REFERS TO CONDI 
unit' HAS BEEN SPECIFICALLY ESTABLISHED 


4 
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] EXAMPLE 
del (zerodivide, overflow, any other) condition; 
on zerodivide begin; 
end; 
on any other begin; 


end; 


Signal overflow; 


1 BACKWARD TRACE OF STACK LOOKS FOR CONDITION HANDLER TWICE FOR 
EACH FRAME: 


1 LOOKS FOR SPECIFIC CONDITION HANDLER FIRST 


J LOOKS FOR CONDITION HANDLER FOR ‘any other' SECOND 


] THE ‘cleanup’ CONDITION IS AN EXCEPTION IN THAT IT DOES NOT 
INVOKE THE any other HANDLER 
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# THERE IS A DEFAULT HANDLER ‘default_error_handier_' 


@ THE PROGRAM, initialize _process_, HAS ONLY ONE 'on unit' (FOR THE 
CONDITION any_other) . 


1 THE any other CONDITION HANDLER CALLS default _error_handler_ $wall 


0 default_error_handler_ CHECKS TO SEE WHICH CONDITION WAS SIGNALLED 
] EXECUTES DIFFERENT CODE BASED ON THE CONDITION 


I NOTIFIES USER IF IT WAS NOT SET UP TO HANDLE CONDITION (EXAMPLE: 
USER DEFINED CONDITIONS AND program interrupt 


f SEVERAL CONDITIONS RESULT IN CALL TO get_to_cl_$unclaimed_ signal 
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d—— ON UNIT ESTABLISHED FOR any_other 


Sem SIGNAL XYZ 


initialize process_ [jem ON UNIT ESTABLISHED FOR any_other 
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ACTION TAKEN IF NO ‘on unit' IS FOUND ON STACK 


0 default _error_handler $wall SETS UP CONDITION HANDLER FOR any other 
THAT RESULTS IN A CALL TO default _error_handler_$wall_ ignore pi 


0 THUS, A “CONDITION WALL" IS SET UP BETWEEN PROGRAMS RAISING 
CONDITIONS THAT HAVE NO HANDLERS FOR THEM & PROGRAMS RUN AT A 
NEW COMMAND LEVEL THEREAFTER 


I THE WALL IS TRANSPARENT TO THE ‘program _interrupt' AND 'finish' 
CONDITIONS 
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"program interrupt’ CONDITION 
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program _ interrupt: pi: proc; 


del program interrupt condition; 
del signal_ entry options (variable) ; 
del start entry options (variable); 


call signal ("program_interrupt", ...); 

if handler_was_found 

then call start; 

else call com_err_ (..., "program_interrupt", "There is no suspended 
invocation of a subsystem that supports the use of 
this command."); 


end /* program_interrupt */; 
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‘program interrupt’ CONDITION 


@ EXAMPLE DEMONSTRATING THAT ‘program interrupt’ "PENETRATES THE WALL" 


handler: proc; 


del (program_interrupt, 


quit, 
zerodivide) condition; 
del sysprint file; 


on zerodivide go to A; 
on program interrupt go to B; 


Signal quit; 

A: put skip list ("ZERODIVIDE HAPPENED"); 
put skip; 

B: put skip list ("PROGRAM INTERRUPT HAPPENED") ; 
put skip; 


end /*® handler #/; 


r 14:52 0.153 2 


! handler 
QUIT 
r 14:52 0.265 3 level 2 


! signal zerodivide 
Error: Attempt to divide by zero at signal$j;1101 
(>system_library standard>bound_ command env_) 
system handler for error returns to command ievel 
r 14:52 0.524 20 level 3 

! signal program interrupt 


PROGRAM INTERRUPT HAPPENED 
r 14:52 0.221 7 
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PARTIAL STACK HISTORY OF EXAMPLE 


HANDLER 


ABBREV 


HANDLER 
LiSTeN_ 


iMtT_PROC_ 


(sigan auit > 
—— > 


UNCLAIMED SIGNAL 
TANY OTHERL 
SIGNAL _ 
“WALL IGNORE PL 
ANY OTHER 1 
SIGNAL | 
SIGNAL © 
CPL 
ABBREV 
LISTEN. LISTEN 
UNCLAIMEO_SIGNAL UNCLAIMED SIGNAL UNCLAIMED SIGNAL 
0_E_4_SWALL O_€_H_SWALL D_E_H_SWALL 
“ANY _OTHER2 ANY_OTHER 2 
SIGNAL _ SIGNAL _ 
PLI_SIG_ FROM_OFS_ PLY_SIG_FROM_OPS_ PLI_SiG_ FROM _OPS_ 
HANDLER “HANDLER HANOLER 
CPL CPL : {_P_ 


—— ———————_ BET 
ABBREV SIGHAL ABBREV PROGRAM ABBREV 


ZERODIVIDE : INTERRUPT 
ome LISTEN © LISTEN 


LISTEN 
INIT _PROC_ INIT_PAQC_ (NIT_PROG_ 


sFOnNINWSsqTUT MELSON 


NOILIGNOO 


‘program interrupt' CONDITION 


@ NOTE: ‘any other' CONDITION HANDLERS SHOULD PASS ON THE 
"program interrupt’ CONDITION (SEE continue _ to signal _ AND 
find _condition_info_) 
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SUMMARY OF CONDITION HANDLING MECHANISM 


ae ED ee ee 


CONDITION X RAISED 


EXAMINE MOST 
RECENT 
ACTIVATION 


IS THERE A HANDLER 
ESTABLISHED IN THIS 
ACTIVATION FOR 
CONDITION X? 


YES 


EXAMINE NEXT 
PREVIOUS 


INVOKE THE 
HANDLER 


ACTIVATION 


IS THERE A DEFAULT 
HANDLER ESTAB- 
LISHED IN THIS 
ACTIVATION FOR 

ANY OTHER? 


NO | IS THIS THE DOES HANDLER | 
OLDEST WANT SEARCH 
ACTIVATION? CONTINUED? 


YES NO 


NO HANOLER i ; 
FOR THIS RETURN 


CONDITION 
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REVIEW OF PL/I DEFINED CONDITIONS 


Default Error ee : 
: Undefined if hit | Can be Enabled/ Disabled by 
Handler Signals | End of On Unit | Disabled Default 


ee 
Ee ES 


conversion | 
endfile 


transmit 


a 


ae 


2 


NOTE THAT THE ‘size' CONDITION IS ENABLED DURING PL/I I/O 
Cpl signal _ from_ops_), AND CONSEQUENTLY, A PL/I PROGRAM WHICH IS 
EXECUTING ‘put! “STATEMENTS 70. THE 'sysprint! FILE MAY CAUSE ‘size! 
CONDITIONS TO BE SIGNALLED EVEN THOUGH THE CONDITION IS NOT ENABLED IN 
THE PROGRAM ITSELF 
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REVIEW OF PL/I DEFINED CONDITIONS 


@ CONDITIONS IN THE PRECEDING TABLE WERE COVERED IN EARLIER COURSES, 
HOWEVER, THE ‘finisn', ‘area’ AND ‘storage’ CONDITIONS ARE COVERED 
BELOW SINCE THEY ARE NOT USUALLY FULLY UNDERSTOOD IN AN INTRODUCTORY 
COURSE 


I ‘'finish' CONDITION 


I THE FINISH CONDITION IS SIGNALLED JUST PRIOR TO RUN UNIT OR 
PROCESS TERMINATION 


1 IT IS SIGNALLED BY A STOP STATEMENT OR BY COMMANDS SUCH AS 
"stop run', 'logout' AND 'new_proc' 


0 IT BEHAVES JUST LIKE 'program_interrupt' IN THAT IT "PENETRATES 
THE WALL" 


1 ALL CONDITION HANDLERS, WHETHER THEY HANDLE 'finish' OR NOT, 
SHOULD PASS THIS CONDITION ON (BY CALLING continue to_signal_) 
SO THAT ALL PROGRAMS WILL BE NOTIFIED OF THE IMPENDING PROCESS, 
OR RUN UNIT, DESTRUCTION 
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REVIEW OF PL/I DEFINED CONDITIONS 


0 ‘area’ CONDITION 


I AN ATTEMPT HAS BEEN MADE TO ALLOCATE STORAGE IN A PL/I '‘area't 
VARIABLE WHICH DOES NOT HAVE SUFFICIENT STORAGE FOR THE ATTEMPTED 
ALLOCATION 


I PRINTS A MESSAGE AND SIGNALS THE ERROR CONDITION 


1 EXAMPLE 


del (p,q,r) ptr; 

del (A,B) (1000) fixed bin based; 
del C area(2000) static; 

del d float bin based; 


allocate A set(p) in(C); 
allocate d set(q) in(C); 


allocate B set(r) in(C); 
/*® causes ‘area' condition (unless intervening 
'free' statements were executed) #/ . 


1 'storage' CONDITION 


1 AN ATTEMPT HAS BEEN MADE TO GROW A STACK SEGMENT PAST ITS 
MAXIMUM LENGTH 


= 


GENERALLY OCCURS AS A RESULT OF ATTEMPTING TO GENERATE A LARGE 
AMOUNT OF ‘automatic' STORAGE, OR AS A RESULT OF A RUNAWAY 
RECURSIVE PROCEDURE 


IT IS ALSO SIGNALLED IF A PL/I PROGRAM OVERFLOWS THE SYSTEM FREE 
STORAGE AREA 
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SOME SYSTEM-DEFINED CONDITIONS 


@ THE MULTICS SYSTEM HAS DEFINED SOME CONDITIONS OF ITS OWN 


@ SOME OF THE USEFUL SYSTEM-DEFINED (NON-PL/I) CONDITIONS ARE LISTED 
BELOW: 


I active function_error, command_error 


1 ARE SIGNALLED BY THE active fne_err_ AND com_err_ SUBROUTINES 
RESPECTIVELY 


] DEFAULT HANDLER FOR command error PRINTS A MESSAGE AND RETURNS 


] DEFAULT HANDLER FOR active function_error PRINTS AN ERROR 
MESSAGE AND RETURNS TO A NEW COMMAND LEVEL 


J cleanup 


l SIGNALLED TO THOSE PROCEDURES OWNING STACK FRAMES TO BE DISCARDED 
AS A RESULT OF A NON-LOCAL TRANSFER 


1 THIS IS A VERY ATYPICAL USE OF THE CONDITION MECHANISM, SINCE 
'cleanup' IS SIGNALLED IN EVERY FRAME BETWEEN THE CURRENT 
STACK FRAME AND THE FRAME CONTAINING THE TARGET OF THE NON-LOCAL 
TRANSFER 

I TYPE OF THING USUALLY DONE IN A 'cleanup' HANDLER 
I CLOSE FILES WHICH HAD BEEN OPENED IN THAT ACTIVATION BLOCK 
I FREE ALLOCATED ‘'controlled' OR 'based' VARIABLES 

1] REINITIALIZE STATIC VARIABLES 

I 


1 THIS WOULD INTERFERE WITH THE ONE ALREADY IN PROGRESS 
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SOME SYSTEM-DEFINED CONDITIONS 


1 fault_tag 1 


I SIGNALLED WHEN AN ATTEMPT IS MADE TO ACCESS THROUGH AN 
UNINITIALIZED POINTER OR A POINTER CONTAINING INVALID DATA 


I illegal_opeode, illegal procedure 


J SIGNALLED WHEN AN ATTEMPT IS MADE TO EXECUTE AN INVALID OR 
PRIVILEGED MACHINE INSTRUCTION 


1 linkage_error- 


J SIGNALLED WHEN THE DYNAMIC LINKING MECHANISM OF MULTICS CAN 
NOT LOCATE AN EXTERNAL OBJECT 


I. lockup 


] SIGNALLED WHEN A PROGRAM IS EXECUTING A TIGHT LOOP OF CODE 


‘FOR TOO LONG A TIME 


T null_pointer 


0 SIGNALLED WHEN AN ATTEMPT IS MADE TO USE AN INVALID (NULL) 
POINTER 


I out_of bounds 


) SIGNALLED WHEN AN ATTEMPT IS MADE TO REFER TO A LOCATION 
BEYOND THE CURRENT LENGTH OF A SEGMENT 
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SOME SYSTEM-DEFINED CONDITIONS 


1 program_ interrupt 


0 SIGNALLED WHEN THE USER HAS ISSUED THE ‘program interrupt’ 
COMMAND 


I quit 


0 SIGNALLED WHEN THE USER HITS THE 'break' OR ‘attention' KEY 
ON HIS/HER TERMINAL (THE DEFAULT HANDLER PRINTS THE WORD "QUIT" 
ON THE USER'S TERMINAL, ABORTS THE PROGRAM, AND ESTABLISHES A 
NEW COMMAND LEVEL) 


) IN GENERAL, USER PROGRAMS SHOULD NOT HANDLE THE 'quit' CONDITION 


] record quota overflow 


0 SIGNALLED WHEN A USER ATTEMPTS TO ALLOCATE A RECORD IN SECONDARY 
STORAGE WHICH WILL OVERFLOW HIS/HER ALLOTTED LIMIT 


] seg _fault_error 
) SIGNALLED WHEN AN ATTEMPT IS MADE TO USE A POINTER WITH AN 
INVALID SEGMENT NUMBER, AND CAN BE CAUSED BY: 


I THE DELETION OR TERMINATION OF A SEGMENT AFTER THE POINTER 
IS INITIALIZED 


i THE POINTER IS NOT INITIALIZED IN THE CURRENT PROCESS 


I THE USER HAS NO ACCESS TO THE SEGMENT 
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SOME SYSTEM-DEFINED CONDITIONS 


3 | YOU ARE NOW READY FOR WORKSHOP 
| mn 


Od 
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(End Of Topic) 


The Multics Input/Output 


Characteristics. ... 


The Multics I/O Mechanism... . 
Protocols Supported. 
The More Popular I/O Modules 


Performing Multics I/O . 


THE ‘tiox ' SUBROUTINE. 
I/O Control Blocks 
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Toric VII THE MULTICS 1/0 SYSTEM Topic VIT 


OBJECTIVES: 


Upon completion of this topic, students should be able to: 


1. Define the followings terms: 
I/O switch 
I/O module 
stream 1/0 © 
record seauential I/0 
record blocked 1/0 


indexed I/06 


2. List the more rorular 1/0 modules. 


3. List the steers required to perform I/O. 


&. Describe an I/0 control block (IOCB?}. 


Multics VII-1 


FASC 


CHARACTERISTICS 


@ THE MULTICS INPUT/OUTPUT SYSTEM IS A FLEXIBLE, GENERALIZED I/O SYSTEM 
CAPABLE OF SUPPORTING SEVERAL PROTOCOLS OF DATA TRANSMISSION TO A 
FULL COMPLEMENT OF FILES AND DEVICES 


@ 1/0 SYSTEM BASIC CHARACTERISTICS: 


1 LOGICAL INPUT/OUTPUT REQUESTS ARE USED RATHER THAN DEVICE-SPECIFIC 
PHYSICAL REQUESTS 


] DEVICE INDEPENDENCE IS ACHIEVED VIA THE MULTICS I/0 SWITCH MECHANISM 


1 UNFAMILIAR OR NEW DEVICES CAN BE ADDRESSED VIA THE IMPLEMENTATION 
OF SITE-=PREPARED INPUT/OUTPUT INTERFACE MODULES 
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THE MULTICS I/O MECHANISM 


@ THE I/O MECHANISM USES THE FOLLOWING CONSTRUCTS: 


1 SWITCH, SWITCHNAME 


I 


A SWITCH IS A LOGICAL CONSTRUCT USED TO DESIGNATE THE TARGET 
OF AN INPUT OR OUTPUT REQUEST 


ASSOCIATED WITH AN I/O SWITCH IS A "SWITCHNAME" 


ALL I/O REQUESTS ARE DIRECTED TO A "SWITCH" WHICH IS "ATTACHED" 
BY A DEVICE-DEPENDENT PROGRAM, CALLED AN I/0 MODULE, TO A 
PARTICULAR DEVICE OR FILE : 


THE SUPPORTING DATA STRUCTURE OF A SWITCH IS AN I/0 CONTROL 
BLOCK (IOCB) 


) INPUT/OUT PUT ‘MODULE 


A DEVICE-DEPENDENT COMMUNICATION MODULE WHICH ACTS AS THE 
INTERFACE BETWEEN THE USER'S LOGICAL I/0 REQUESTS AND THE 
HARDWARE-LEVEL I/O SYSTEM 


TRANSLATES THE USER'S LOGICAL REQUESTS INTO THE PHYSICAL REQUESTS 
APPROPRIATE TO THE TYPE OF DEVICE OR FILE FOR WHICH IT WAS 
WRITTEN 


SYSTEM STANDARD MODULES SUPPORT I/O TO/FROM BASIC DEVICES (TAPE, 
REMOVABLE DISK, TERMINAL DEVICES, CARD READERS, ETC.} AND 


FILES (SEGMENTS IN THE VIRTUAL MEMORY) 
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THE MULTICS I/O MECHANISM 


PROGRAM 


1/0 SWITCH» 
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THE MULTICS I/O MECHANISM 
PROTOCOLS SUPPORTED 


@ FOUR BASIC I/0 PROTOCOLS (FILE STRUCTURES) SUPPORTED 


] THE TYPE OF PROTOCOL BEING USED LIMITS THE REQUESTS THAT CAN BE 
SATISFIED 


I CERTAIN I/O MODULES SUPPORT ONLY ONE PROTOCOL, SOME I/O MODULES 
SUPPORT ALL THE PROTOCOLS 


] THEY ARE: 


1 1) STREAM INPUT/OUT PUT 


I 


=! 


A STREAM FILE IS A SEQUENCE OF ASCII CHARACTERS, SEPARATED 
BY NEWLINE AND NEWPAGE CHARACTERS 


OFTEN CALLED AN "UNSTRUCTURED" FILE 

EXAMPLES: TERMINAL DIALOG, TEXT EDITOR CREATED SEGMENTS, 
TAPES WRITTEN VIA tape mult_ 

RECORD SEQUENTIAL INPUT/OUT PUT 


A "STRUCTURED" FILE OF VARIABLE LENGTH RECORDS, EACH RECORD 
REPRESENTING ONE STRUCTURE 


A RECORD FILE MAY BE ACCESSED IN "SEQUENTIAL" PROTOCOL, 
WHICH MEANS THAT THE CURRENT RECORD AND NEXT RECORD ARE 
WELL=-DEF INED 


EXAMPLES: TAPES WRITTEN VIAtape_ibm_ ORtape_ansi_, CERTAIN 
VIRTUAL MEMORY SEGMENTS 
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THE MULTICS I/O MECHANISM 
PROTOCOLS SUPPORTED 


0 3) RECORD BLOCKED INPUT/OUT PUT 


I A RECORD FILE MAY BE CREATED IN LOGICAL BLOCKS, THUS ALLOWING 
I/O TO BE DONE A BLOCK AT A TIME 


— BLOCK SIZE IS FIXED 
T A BLOCK CONTAINS 


I] ONE RECORD (WITH POTENTIAL WASTED SPACE) IF IN A VIRTUAL 
MEMORY FILE 


I ONE OR MORE RECORDS IF ON ANSI OR IBM TAPE 
I SPECIFY BLOCKED MODE AT ATTACH TIME 


1 4) INDEXED INPUT/OUT PUT 
I AN INDEXED FILE IS A "KEYED" FILE, IMPLEMENTED AS A 
MULTI-SEGMENT FILE WITH ONE (OR MORE) COMPONENTS HOLDING 
THE "KEY VALUES", AND ONE (OR MORE) COMPONENTS HOLDING THE 
"DATA RECORDS" . . 


1 AN INDEXED FILE MAY BE ACCESSED IN EITHER "KEYED SEQUENTIAL" 
MODE, OR "KEYED DIRECT" MODE 


] MUST BE IN THE VIRTUAL MEMORY 
] EXAMPLE: "RELATIONS" IN A MRDS DATABASE 


1 PL/I DEDUCES THE PROTOCOL BY EXAMINING LANGUAGE I/O STATEMENTS 
AND/OR THE ATTACH DESCRIPTION 
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THE MULTICS I/O MECHANISM 
THE MORE POPULAR I/O MODULES 


@ SOME OF THE SYSTEM STANDARD I/O MODULES, THEIR FUNCTIONS, AND THE 
PROTOCOLS SUPPORTED ARE: 


1) vfile_ 
2) tty_ 
3) diseard_ 


4) syn 


_ 5) rdisk_ 


6) record _stream_ 


7) -tape_mult_ 

8) tape _ibm_ 
tape_ ansi_ 

9) tape_nstd_ 


10) bisyne_ 


11) audit_ 
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FUNCTION PROTOCOLS SUPPORTED 

I/O TO/FROM SEGMENTS IN ALL 

THE VIRTUAL MEMORY 

I/O TO/FROM TERMINAL STREAM 

DEVICES 

OUTPUT SINK ALL 

ALLOWS ONE SWITCH TO SERVE AG 

AS A SYNONYM FOR ANOTHER 

SWITCH 

I/O TO/FROM REMOVABLE, NON- SEQUENTIAL, 

MULTICS DISK PACKS KEYED, OR 
BLOCKED ~ 

ALLOWS RECORD I/O OPERATIONS STREAM 

TO BE DIRECTED TO A STREAM <=> 

FILE AND VICE VERSA SEQUENTIAL 

I/O TO/FROM A MULTICS STREAM 

FORMAT TAPE 

I/O TO/FROM A TAPE FILE IN SEQUENTIAL, 

IBM OR ANSI FORMAT BLOCKED 


I/O TO/FROM TAPES IN NON-STANDARD SEQUENTIAL 
OR UNKNOWN FORMATS 


I/O ACROSS A BINARY SYNCHRONOUS STREAM 
COMMUNICATIONS CHANNEL 


INTERCEPTS I/O ACTIVITY ON A STREAM 


GIVEN SWITCH, ALLOWING LOGGING 
AND EDITING OF DATA 
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THE MULTICS I/O MECHANISM 
PERFORMING MULTICS I/0 


@® STEPS REQUIRED TO PERFORM I/0 


I 1) THE SPECIFIED SWITCH MUST BE "ATTACHED" (INITIALIZED) BY A 
SPECIFIED I/O MODULE TO SOME TARGET DEVICE OR FILE (SUBSEQUENT 
REQUESTS DIRECTED TO THE SWITCHNAME OPERATE VIA THE I/0 MODULE 
ON THE TARGET DEVICE OR FILE) 


0 2) THE SWITCH MUST BE "OPENED" IN A MODE COMPATIBLE WITH THE 
TYPE OF DEVICE OR FILE BEING MANIPULATED 


] 3) INPUT/OUTPUT OPERATIONS CAN NOW BE DIRECTED TO THE SWITCH 
(OPERATIONS MUST BE CONSISTENT WITH THE ATTACHMENT AND OPENING 
MODE OF THE SWITCH) 


1 4) THE SWITCH MUST BE "CLOSED" LEAVING THE SWITCH IN THE STATE 
IT WAS PRIOR TO THE "OPENING" (THAT IS, IT MAY NOW BE OPENED 
WITH A DIFFERENT MODE) 


1 5) THE SPECIFIED SWITCH MUST BE "DETACHED" BREAKING THE ASSOCIATION 
BETWEEN THE SWITCHNAME AND THE I/O MODULE AND TARGET (HENCE, THE 
SWITCH MAY BE ATTACHED IN A NEW WAY) 


Not To Be Reproduced T-7 F15C 


THE MULTICS I/O MECHANISM 
PERFORMING MULTICS I/0 


QS a ae 


! ATTACH CLOSE 


DETACH CLOSE 


ETC. 
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THE MULTICS I/O MECHANISM 
PERFORMING MULTICS I/0 


@® ALL I/O OPERATIONS CAN BE PERFORMED AT THREE BASIC LEVELS: 
1 LANGUAGE LEVEL = 'open', 'close', 'get', 'read', 'put', ‘write’ 
0 COMMAND LEVEL - THE ‘io call' COMMAND 
| SUBROUTINE LEVEL - THE ote SUBROUTINE 


J] EXAMPLES (THE FOLLOWING ARE EQUIVALENT): 


J] PL/I 


open file (x) title ("vfile_ user_file") stream output; 


io_call attach x vfile_ user_file 
io_ call open x stream_output 
] SUBROUTINE LEVEL 
Call iox_ $attach_ name ("x", iocb ptr, "vfile_ user_file", 


ref ptr, code); 
call iox_$open (iocb ptr, 2, "O0"b, code); 


1 LANGUAGE VS. 1/0 SYSTEM 


PL/I STATEMENT EQUIVALENT I/O CALLS 


attach 
open 
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THE MULTICS I/0 MECHANISM 
PERFORMING MULTICS I/0 


@® THE ATTACHMENT AND DETACHMENT OF A SWITCH CAN BE PERFORMED EITHER 
EXTERNALLY TO A PROGRAM OR INTERNALLY BY THE PROGRAM ITSELF 


I 


IF THE SWITCH IS ATTACHED EXTERNALLY, THE PROGRAM RECOGNIZES 
THIS ATTACHMENT, HONORS THIS PRIOR ATTACHMENT, AND IGNORES THE 
SPECIFIED INTERNAL ATTACH DESCRIPTION (THUS YIELDING DEVICE 
INDE PENDENCE) 


IF THE SWITCH HAS NOT BEEN ATTACHED EXTERNALLY, THE ATTACH 
DESCRIPTION SUPPLIED BY THE PROGRAM (EITHER EXPLICITLY OR 
IMPLICITLY) WILL BE USED TO ATTACH THE SWITCH 


IF THE SWITCH IS ATTACHED EXTERNALLY, IT MUST BE DETACHED EXTERNALLY 


I IF THE SWITCH IS ATTACHED INTERNALLY BY EXECUTION OF THE 'open' 
STATEMENT, IT WILL BE DETACHED BY EXECUTION OF THE 'close' 
STATEMENT 


@ THE ABOVE STATEMENTS SIMILARLY APPLY TO THE OPEN AND CLOSE OPERATIONS 
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THE MULTICS I/O MECHANISM 
PERFORMING MULTICS I/0 


) EXAMPLE 


X3 proc; 


del line char(80); 
del (abe, xyz) file; 
del i; 


open file (abe) input; 
open file (xyz) output; 


do i= 1 to 50; 
get file (abe) list (line); 
put file (xyz) list (line); 
end; 


close file (abc), file (xyz); 


end /® x ¥#/; 


] TO HAVE OUTPUT. SENT TO TERMINAL INSTEAD OF FILE xyz USER COULD 
TYPE THE FOLLOWING: 


! io call attach xyz syn_ user_output 
! x ; | 


! . io_call detach xyz 
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THE 'iox ' SUBROUTINE 


iox_ IS THE USER-RING INTERFACE TO THE MULTICS INPUT/OUTPUT SYSTEM 


ALL I/O OPERATIONS ISSUED AT THE USER-RING LEVEL (WHETHER FROM 
COMMAND LEVEL, LANGUAGE LEVEL, OR DIRECT iox_ CALL) RESULT IN A 
CALL TO iox 


iox PROVIDES ENTRY POINTS FOR ALL INPUT/OUTPUT OPERATIONS 


EVERY iox_ ENTRY POINT REQUIRES AN ARGUMENT DENOTING THE PARTICULAR 
I/O SWITCH (ACTUALLY THE IOCB) INVOLVED IN THE OPERATION 


IF AN ENTRY POINT REQUIRES THE I/O SWITCH TO BE OPEN, AND IF IT 
IS NOT, THE CODE ‘error table $not_open' IS RETURNED 


IF THE I/O SWITCH IS OPEN, BUT THE OPERATION IS NOT ALLOWED FOR 
THAT OPENING MODE, THE CODE ‘error _table $no_operation' IS RETURNED 
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THE 'iox ' SUBROUTINE 


@ THE MAJOR ENTRY POINTS OF iox_ CAN BE CLASSIFIED AS FOLLOWS: 


J ATTACHING/DETACHING 
I iox_$attach_name 
Q iox_$attach_ptr 
f iox_$detach_iocb 
0 iox_$destroy_iocb 
0 iox_$find_iocb 
q _lox_$look_ioeb 


0 iox_$move attach 


1 OPENING/CLOSING 
1 iox_$open 


f iox_$close 


0 STREAM I/O REQUESTS 
1 iox_$get_chars 
0 iox_$get_line 


) iox_$put_chars 
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E 'iox ' SUBROUTINE 


2 RECORD I/O REQUESTS 
I iox_$delete_record 
1 iox_$read_key 
1 iox_$read_length 
f iox_$read_record 
1 iox $rewrite_record 
0 iox_$seek_key 


1 iox_ $write record 


= 


] CONTROL REQUESTS 
I iox $control 
1 iox_$modes 


1 iox_ $position 
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I/O CONTROL BLOCKS 


@ WHAT IS AN I/O CONTROL BLOCK (IOCB)? 
r EVERY SWITCHNAME HAS ASSOCIATED WITH IT AN ‘'IOCB' 
) AN 'IOCB' IS A STANDARD DATA STRUCTURE 
] IT IS THE PHYSICAL REALIZATION OF A SWITCH 
I THEY ARE FOUND IN THE USER'S PROCESS DIRECTORY 


— AN 'IOCB' IS CREATED BY iox_ WHEN A SWITCHNAME IS USED IN AN 
"ATTACH STATEMENT" OR "ATTACH COMMAND" FOR THE FIRST TIME IN A 
PROCESS 


] IF THE SAME SWITCHNAME IS USED LATER IN THE PROCESS, THE SAME 
"TOCB’ IS REUSED 


I THUS THERE IS A ONE TO ONE MAPPING BETWEEN SWITCHNAMES AND 
TOCB'S 


I] ONCE AN 'IOCB' IS CREATED, IT LIVES THROUGHOUT THE PROCESS (UNLESS 
EXPLICITLY DELETED) 
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I/Q CONTROL BLOCKS 


/*® BEGIN INCLUDE FILE ..... iocb.incl.pli ..... 
13 Feb 1975, M. Asherman */ 
/* Modified 11/29/82 by S. Krupp to add new entries and 
to change version number to I0X2. *#/ 
/* format: style2 *#/ — 


del 1 iocb aligned based, 
/* I/O control block. */ 
version character (4) aligned, 
/* IOX2 */ 
name char (32), 
/* I/O name of this block. */ 
actual_jiocb ptr ptr, 
/* IOCB ultimately SYNed to. */ 
attach descrip ptr ptr, 
/* Ptr to printable attach description. */ 
attach data_ptr ptr, 
/* Ptr to attach data structure. */ 
open_descrip ptr ptr, 
/* Ptr to printable open description. */ 
open _data ptr ptr, 
/*”Ptr To open data structure (old SDB). 
reserved : bit (72), 
/* Reserved for future use. */ 
detach_iocb entry (ptr, fixed (35)), 
/* detach_ioeb(p,s) #/ 
open entry (ptr, fixed, bit (1) aligned, 
fixed (35)), 
/* open(p,mode,not_used,s) */ 


N 


my NO NY NY WHO WY NWO NN NW 


2 close entry (ptr, fixed (35)), 
/* close(p,s) */ 
2 get_line entry (ptr, ptr, fixed (21), 


fixed (21), fixed (35)), 
/* get_line(p,bufptr ,buflen,actlen, s) */ 
2 get_chars entry (ptr, ptr, fixed (21), 
fixed (21), fixed (35). 
/* get_ chars(p,bufptr, buflen, actlen ,3) */ 
put_chars entry (ptr, ptr, rixed (21), 
fixed (35)), 
/* put_chars(p,bufptr,buflen,s) */ 
2 modes entry (ptr, char (*), char (*), 
fixed (35)), 
ioe modes p,newmods) Oldmode,s) */ 
-ian entry (ptr, fixed. fixed (21) 
fixed (35)), 
/* position(p,ui,u2,s) */ 
2 control entry (ptr, char (*), ptr, 
fixed (35)), 
/* control(p,order,infptr,s) */ 
2 read _ record entry (ptr, ptr, fixed (21), 
fixed (21), fixed (35)), 
/* read _record(p,buf ptr, buflen, actlen ,8) 87 
2 write_ record entry (ptr, ptr, fixed 2175 


ND 


Nw 
q3 
oO 
(a 
{-- 
(ct 
{-- 
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I/O CONTROL BLOCKS 


fixed (35)), 
/* write_record(p,bufptr,buflen,s) */ 
2 rewrite record entry (ptr, ptr, fixed (21), 
fixed (35)), 
/* rewrite_record(p,bufptr ,buflen i) ¥/ 


2 delete_ record entry (ptr, fixed (35)), 
/* delete_record(p,s) */ 
2 seek_key entry (ptr, char (256) varying, 


fixed (21), fixed (35)), 
/* seek _key(p,key,len,s) */ 
2 read_key entry (ptr, char (256) varying, 
fixed (21), fixed (35)), 
/* read_key(p,key,len,s) */ 


2 read_length entry (ptr, fixed (21), fixed (35)), 
/* read _length(p,len,s) */ 
2 open_file entry (ptr, fixed bin, char (*), 


bit (1) aligned, fixed bin C352); 
/* open_ filet paede: desc ,not_used,s) */ 


2 close file entry (ptr ,~ char (#), fixed bin (35)), 
/* Close _file(p,desc,s) */ 
2 detach entry (ptr, char (*), fixed bin (35)); 


/* detach(p,desc,s) */ 


declare iox _$iocb_ version sentinel 
character (4) aligned external static; 


/*® END INCLUDE FILE ..... Lloeb.inecl.pl1 ..... #/ 
del 1 attach descrip based aligned, 
2 length fixed bin (17), 


2 string char (0 refer (attach descrip.length)); 
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I/O CONTROL BLOCKS 


@ AN ATTACH DESCRIPTION IS A CHARACTER STRING CONVEYING THE FOLLOWING 
INFORMATION: 


I] MODULE NAME 


IT MODULE-=SPECIFIC ARGUMENTS, SUCH AS: 
I PATHNAME (vfile_) 
1 CHANNEL NAME (tty_, bisync_) 
( VOLUME ID (tape_ibm_, tape_ansi_, tape mult_, tape _nstd_) 
0 DISK_DRIVE_ID AND PACK_ID (rdisk_) 


0 SWITCHNAME (syn_, record stream_) 


1 MODULE-SPECIFIC CONTROL ARGUMENTS, SUCH AS: 
] -extend (vfile_, tape_ibm_, tape _ansi_) 
0 -density (tape _ibm_, tape_ansi_, tape _mult_) 
Q -block (tape_ibm_, tape_ansi_) 


9 -blocked (vfile_) 


1 COMPLETE DESCRIPTIONS OF THE I/O MODULES AND THE ARGUMENTS SPECIFIED 
AT ATTACH TIME ARE IN Multiecs Subroutines & I/0 Modules (AG93) 
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I/Q CONTROL BLOCKS 


@® THE PRINCIPAL COMPONENTS OF AN 'IOCB' ARE 'pointer' VARIABLES AND 
‘Tentry' VARIABLES 


@ THERE IS ONE '‘entry' VARIABLE FOR EACH I/O OPERATION, WITH THE 
EXCEPTION OF THE ATTACH OPERATION 


@® TO PERFORM AN I/O OPERATION THROUGH THE SWITCH, THE APPROPRIATE 
ENTRY VALUE IN THE CORRESPONDING ‘'IOCB' IS CALLED 


I FOR EXAMPLE: 
call iox_$put_chars(iocb ptr,.....); 
CAN BE THOUGHT OF AS: 


call iocb_ptr->ioceb.put_chars(.....); 
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I/O CONTROL BLOCKS 


@ WHEN iox_$attach_name IS CALLED IT: 
] CREATES/LOCATES THE 'IOCB' ASSOCIATED WITH THAT SWITCHNAME 
[ INITIALIZES SOME OF THE ELEMENTS IN THE 'IOCB' STRUCTURE 


] CALLS <module_name>$<module_ name> attach 


0 THUS THERE NEED BE NO ENTRY FOR THE ATTACH OPERATION IN THE 
‘IOCB' 


1 THIS ENTRY POINT IN THE I/O MODULE FINISHES THE INITIALIZATION 
OF THE ‘IOCB' 


] FOR EXAMPLE, IF THE I/0 MODULE INVOLVED IN THE ATTACHMENT WAS 
vfile : 


I vfile $vfile attach IS CALLED 


f AFTER THE ATTACHMENT (INITIALIZATION) IS COMPLETE: 
I iocb.open CONTAINS THE ENTRY TO vfile $open 


1 iocb.close CONTAINS THE ENTRY iox_$err_not_open 
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I/O CONTROL BLOCKS 


@ AFTER THE ATTACHMENT OF THE SWITCH, EVERY I/O OPERATION ON THAT 
SWITCH REFERENCES THE CORRESPONDING ‘'IOCB' TO FIND THE ENTRY POINT 
AT WHICH TO START EXECUTION 


I ONE OF TWO ACTIONS MAY RESULT: 
I iox_ GENERATES AN ERROR MESSAGE (IF IT IS AN ILLEGAL OPERATION) 
1 EXECUTION STARTS AT THE APPROPRIATE ENTRY POINT OF THE 
APPROPRIATE MODULE 
1 THIS EXECUTION UPDATES THE ‘IOCB', USUALLY REPLACING SOME 
ENTRY VALUES CAUSING ERROR MESSAGES WITH ENTRY VALUES 
INDICATING ENTRY POINTS IN THE MODULE (AND VISA VERSA) 


) EXAMPLE (IN THE ABOVE CASE): 


BEFORE OPENING AFTER OPENING 


vfile_ $open 


iocb 1ox_$err_not_ open 


IOCB MEMBER 


iocb.open iox_$err_not_closed 


@® IT IS THE RESPONSIBILITY OF THE I/O MODULE TO MAINTAIN THE ACCURACY 
OF ‘THE .*1OCB! 


@ ONLY THE iox ENTRY POINTS RESULTING IN ATTACHMENT OF A SWITCH 
REQUIRE THE MODULE AS AN INPUT ARGUMENT 


IT AFTER THAT TIME, THE 'IOCB' "POINTS TO" THE APPROPRIATE ENTRY 
POINTS IN THE APPROPRIATE MODULE (THE USER NEED ONLY PROVIDE A 
POINTER TO THE 'IOCB') 
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I/O CONTROL BLOCKS 


# IN VIEW OF THE ABOVE DISCUSSION OF IOCB'S AND SWITCHES, THE TERM 
"SWITCH" SHOULD MAKE MORE SENSE 


I A SWITCH/IOCB CAN BE THOUGHT OF AS A STRUCTURE CONTAINING TRANSFER 
VECTORS 


YOU ARE NOW READY FOR WORKSHOP 
#5 
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| 7-22 | 
(End Of Topic) 


TOPIC VIII 


The iox_ Multics Subroutine 
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Topic VIII THE IOX_ SUBROUTINE Toric VIII 
OBJECTIVES: 

Uron completion of this topic, students should be able to: 

1. Open and close 1/0 switches usins iox_. 

&. Read data from the user’s terminal. 

3. Display information on the ers terminal. 

4. Read and write stream files. 


5. Read and write seauential and keyed files. 
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INTRODUCTION TO USING iox 


@® WHY USE iox_ RATHER THAN PL/I I/O STATEMENTS? 


1 iox_ IS MORE EFFICIENT 


I WRITTEN IN alm 


1 NUMBER OF MEMORY ACCESSES 
1 iox_ ACCESSES 'IOCB' ONLY 
I PL/I STATEMENTS ACCESS 'FSB! (FILE STATE BLOCK) AND 'IOCB! 


) MORE POWERFUL 


I BETTER ERROR DETECTION 


I ACCEPTED CONVENTION FOR SYSTEM CODE 


@ WARNING: SHOULD NOT MIX iox AND PL/I I/O DUE TO INCONSISTENCIES 
(DIRECT CALLS TO iox_ DO NOT MAINTAIN 'FSB') 
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@® iox 


iox 


OPENING MODES SUPPORTED AND THE iox_ 


EACH OPENING: 


= 
oO 


CO} © NONE WHh— 


SEE 


@® NOT 


— 


Not To 


NAME 


stream input 
stream output 
stream input output 


sequential input 
sequential output 
sequential input output 
sequential update 
keyed sequential input 


keyed sequential output 
keyed _ sequential update 


direct input 


OPENING MODES 


OPERATIONS PERMITTED FOR 


I/O OPERATIONS PERMITTED 


get_line, get_chars, position 
put_chars 
1 +2 


read record, read_length, position 
write_ record 

+5 

4, rewrite record, delete record 


read_record, read_ length, position, 
~seek key, read _key . 

seek key, “write record 

8 + 9,rewrite record ,delete_ record 


read record, read length, seek key 
seek key, write record 
11 + 12, rewrite_ record ,delete record 


direct , output 
direct_ update 
>1ldd>include>iox_modes.incl.pl1 
E: 
THE 'open', 'close', 'controi' 


WITH ANY OPENING MODE 


THE ABOVE NUMBERS ARE USED IN CALLS TO iox_ 


MODES 


THE LONG NAME (AS GIVEN ABOVE) IS USED WITH 


, AND 'modes' OPERATIONS ARE PERMITTED 


TO SPECIFY OPENING 


"io _call' 


PL/I SPECIFIES THE OPENING MODE IN THE FILE DESCRIPTION 


Be Reproduced 


8=2 


F15C 


STANDARD SWITCH ATTACHMENTS 


jwseioput | wsercoutrut | 


user_i/o 


o 
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STANDARD SWITCH ATTACHMENTS 


@ THE MULTICS STANDARD PROGRAMMING ENVIRONMENT MAKES USE OF FOUR SWITCHES 
WHICH ARE ATTACHED AND OPENED AS PART OF THE PROCESS CREATION CYCLE 


@® THE STANDARD ATTACHMENTS ARE: 


user_i/o tty -login_ channel 
Stream input output 

user_input syn_ user_i/o 

user_output ~°syn_ user_i/o 

error output syn_ user_i/o 


@ IN TERMS OF iox_, THESE SWITCHES ARE IDENTIFIED BY THE FOLLOWING 
DECLARATIONS: . 
I del iox_$user_io external pointer; 
1 del iox_$user_input external pointer; 
1 del iox_$user_output external pointer; 


] del iox_$error_output external pointer; 


1 EXAMPLE 


call iox_$put_chars (iox_$user_output, buffer ptr, 
buffer_length, code); 
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Lox ENTRY POINTS 


@ THERE ARE OVER 25 ENTRY POINTS FOR THE iox_ SUBROUTINE (SEVERAL ARE 
PRESENTED IN THE REMAINDER OF THIS TOPIC) 


@ THE FIRST 7 ENTRY POINTS: 
I ARE SUMMARIZED ON THE NEXT 2 PAGES 
1 WILL BE STUDIED IN DETAIL BY REFERRING TO THE SUBROUTINES MANUAL 
] WILL BE USED IN WORKSHOP 6 


I REPRESENT SOME COMMONLY USED ENTRY POINTS THAT WOULD BE USED TO 
PROMPT A USER FOR A KEY AND THEN FIND THE CORRESPONDING RECORD 
IN A KEYED FILE 


@ THE OTHER ENTRY POINTS (STARTING ON PAGE 8-7) WILL BE COVERED IN 
MUCH LESS DETAIL 


@® SEVERAL OPERATIONS INVOLVE THE USE OF A BUFFER 


0 A BUFFER IS A BLOCK OF STORAGE PROVIDED BY THE CALLER OF THE 
OPERATION AS THE TARGET FOR INPUT OR THE SOURCE FOR OUTPUT 


1 A PTR TO THE BUFFER IS PASSED TO iox_ SUBROUTINES 
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iox ENTRY POINTS 


@® iox_$attach name 
@ ACCEPTS A SWITCHNAME 
I RETURNS A POINTER TO THE 'IOCB' FOR THE CORRESPONDING SWITCH 


I ATTACHES THE SWITCH IN ACCORDANCE WITH THE SUPPLIED ATTACH 
DESCRIPTION 


@ iox_$open 


1 OPENING MODE IS SPECIFIED BY A NUMBER (SEE PAGE 8-2) 


® iox_ $get_line 
fi THE NEWLINE CHARACTER SIGNIFIES THE END OF THE LINE 
I A CODE OF ZERO IS RETURNED ONLY IF A NEWLINE CHARACTER IS READ 


] THE NEWLINE ITSELF IS READ INTO THE BUFFER 
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iox ENTRY POINTS 


@ Lox_$seek key 


1 THE NEXT RECORD POSITION AND CURRENT RECORD POSITION ARE SET TO 
THE RECORD WITH THE GIVEN KEY 


I USED BEFORE DOING A read, delete, rewrite, ETC. 


‘@ iox_$read_record 
J READS THE NEXT RECORD IN A STRUCTURED FILE 


1 KEYED READS FIRST REQUIRE A CALL TO iox_ $seek_key 


® iox_$close 


@ iox_$detach_iocb 


DOES NOT FREE THE IOCB'S STORAGE 
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iox ENTRY POINTS 


@ THE REST OF THIS TOPIC WILL SERVE AS AN OVERVIEW OF OTHER iox_ 
ENTRY POINTS 


@ iox $attach ptr 
2 call iOx_$attach_ptr (iocb_ ptr, atd, ref_ptr, code); 


I BEHAVES LIKE iox_$attach_name, EXCEPT iocb ptr IS AN INPUT NOT 
AN OUTPUT VARIABLE 


@® iox $find_iocb 
2 call iox_$find_iocb (switchname, iocb ptr, code); 


I GIVEN A SWITCHNAME, RETURNS A POINTER TO THE IOCB, BUTDOES NO 
ATTACHMENT (IF THE BLOCK DOES NOT ALREADY EXIST, IT IS CREATED) 


0 iox_$find_iocb + iox_$attach_ptr = iox $attach name 


@® iox_ $look_iocb 
9 call iox_$look_iocb (switchname, iocb ptr, code); 


] BEHAVES LIKE iox $find_iocb, HOWEVER DOES NOT CREATE A BLOCK IF 
ONE DOES NOT ALREADY EXIST 
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iop ENTRY POINTS 


@ iox $move attach 
] call iox_$move_ attach (iocb_ ptr1, iocb_ptr2, code); 
I INCLUDED FOR COMPLETENESS (NOT FOR NOVICE USERS) 


J MOVES AN ATTACHMENT FROM ONE ATTACHED SWITCH TO ANOTHER DETACHED 
SWITCH 


I] THE PERFECT EXAMPLE (FOR WHICH move attach WAS WRITTEN) IS THE 
CASE OF file_output, IN WHICH A TEMPORARY SWITCH IS CREATED, THE 
CURRENT ATTACHMENT OF user output IS MOVED TO THAT TEMPORARY 
SWITCH, AND THEN user_output IS ATTACHED TO THE OUTPUT FILE. 


@ iox $destroy iocb 
1 call iox_$destroy_iocb (iocb_ptr, code); 


I FREES THE STORAGE USED BY A DETACHED CONTROL BLOCK 
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i1ox ENTRY POINTS 


@ iox_$get_ chars 
1 call iox $get_chars (iocb ptr, buff_ptr, n, n_read, code); 


I USER REQUESTS n BYTES (CHARACTERS) FROM A STREAM FILE OR DEVICE 
(ACTUALLY NUMBER READ IS n_read BYTES) 


0 IF n = n_read THEN code 


1 
Oo 


I] IF n_read < n THEN code = error_table $short_record 


) IF NEXT BYTE IS "END OF FILE" THEN code = error _table $end of info 
(NOTE THAT THE ‘endfile' CONDITION IS NOT SIGNALLED WHEN USING 
iox_) -. 


0 READS NEWLINE CHARACTERS INTO BUFFER JUST LIKE ANY OTHER CHARACTER 


1 IF n IS GREATER THAN THE SIZE OF THE RECEIVING BUFFER, OVERFLOW 
CHARACTERS WILL BE WRITTEN PAST THE END OF THE BUFFER, YIELDING 
POTENTIALLY DISASTROUS RESULTS 


I BUFFER OUGHT TO BE EXPLICITLY FLUSHED PRIOR TO CALL, BECAUSE 
JUST n_read CHARACTERS WILL BE OVERWRITTEN 


1 ALTERNATIVE: 
del max_buff char(80) based (buff_ptr); 
del buff char (n_read) based (buff_ptr); 
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iox ENTRY POINTS 


@® iox_$put_chars 
1 call iox_$put_chars (iocb_ ptr, buff_ptr, n, code); 
I WRITES n BYTES (CHARACTERS) TO THE UNSTRUCTURED FILE OR DEVICE 


I BUFFER SHOULD CONTAIN A NEWLINE, IF ONE IS INTENDED (THERE IS NO 
*put_line’ ENTRY POINT) 


) IF OPEN FOR stream output THE CHARACTERS ARE APPENDED TO THE END 
OF THE FILE. IF OPEN FOR Stream _ input output FILE TRUNCATION 
OCCURS JUST BEFORE THE NEXT BYTE 


@® iox_$write record 
1 call iox_$write record (iocb_ ptr, buff_ptr, rec_len, code); 
] ADDS A RECORD TO A STRUCTURED FILE 


] IF OPEN FOR sequential_output, THE RECORD IS APPENDED TO THE 
FILE. IF OPEN FOR sequential_ input_ output, FILE TRUNCATION OCCURS 
JUST BEFORE THE NEXT RECORD 


] iox_$seek_key MUST BE CALLED BEFORE DOING A KEYED WRITE IN ORDER 
TO "SET THE KEY" FOR INSERTION 
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iox ENTRY POINTS 


@ iox_ $rewrite_record 
l call iox_$rewrite_ record (iocb ptr, buff_ptr, rec_len, code); 


1 REPLACES THE CURRENT RECORD IN A STRUCTURED FILE THAT HAS BEEN 
OPENED FOR "UPDATE" 


) IF THE CURRENT RECORD POSITION IS NULL, error_table $no_record 
IS RETURNED 


I THUS IT IS FIRST NECESSARY TO "LOCATE" THE RECORD TO BE REPLACED 
(USING read_record, seek_key OR position ENTRY POINTS) 


@® iox $read_ length 
J call iox_$read_length (iocb ptr, rec_len, code); 


J RETURNS THE LENGTH OF THE NEXT RECORD IN A STRUCTURED FILE 


i IF THE NEXT RECORD POSITION IS AT THE END OF FILE, code = 
7 ? 
error table $end of info 


0 APPLICATION: TO DETERMINE HOW LONG THE BUFFER MUST BE IN ORDER 
TO HOLD THE NEXT RECORD TO BE READ (EXAMPLE: VARIABLE LENGTH 
RECORDS ) ' 
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iox_ ENTRY POINTS 


@ iox_$delete record 
1 call iox_ $delete_record (iocb ptr, code); 


1 DELETES THE CURRENT RECORD FROM THE STRUCTURED FILE, WHOSE SWITCH 
MUST BE OPENED FOR "UPDATE" 


l IF THE CURRENT RECORD IS NULL, code = error table $no_record 


0 AGAIN, IT IS FIRST NECESSARY TO "LOCATE" THE RECORD TO BE DELETED 
(USING read_record, seek_key OR position ENTRY POINTS) 


@ iox_ $read_key 
1 call iox_$read_key (iocb_ ptr, key, rec_len, code); 


J RETURNS BOTH THE KEY AND THE LENGTH OF THE NEXT RECORD IN AN 
INDEXED FILE 


I code = error table $end_of_info IF THE NEXT RECORD POSITION IS 
AT THE END OF FILE 


I code = error_table $no_record IF THE NEXT RECORD POSITION IS 
NULL 
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iox ENTRY POINTS 


@ iox_ $position 
0 call iox_$position (iocb ptr, type, n, code); 


1 POSITIONS TO THE BEGINNING OR END OF A FILE, OR SKIPS FORWARD OR 
BACKWARD OVER A SPECIFIED NUMBER OF LINES OR CHARACTERS 
(UNSTRUCTURED FILES) OR RECORDS (STRUCTURED FILES) 

J type IDENTIFIES THE TYPE OF POSITIONING (INPUT) 
0 -1 GO TO THE BEGINNING OF FILE (n = 0) 
0 +1 GO TO THE END OF FILE (n = 0) 
2 Oo SKIP NEWLINE CHARACTERS OR RECORDS (n positive or negative) 
0 2 POSITION TO AN ABSOLUTE CHARACTER OR RECORD (n) 


] 3 SKIP CHARACTERS (stream_input) (n positive or negative) 
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iox ENTRY POINTS 


@ iox_$modes 


J USED TO OBTAIN OR SET MODES THAT AFFECT THE SUBSEQUENT BEHAVIOR 
OF THE SWITCH (BEST KNOWN MODES ARE THOSE ASSOCIATED WITH tty_ 
echoplex ,tabs,polite,etc.) 


1 call iox_$modes (iocb ptr, new_modes, old_ modes, code); 


1 SWITCH MUST BE ATTACHED VIA AN I/O MODULE THAT SUPPORTS MODES 
(EXAMPLE: tty _ SUPPORTS MODES, vfile_ DOES NOT) 


0 FOR A LIST OF THE VALID MODES, SEE THE DESCRIPTION OF THE MODULE 
INVOLVED 


J call iox_$control (iocb_ptr, order, info_ptr, code); 


I info ptr IS NULL OR POINTS TO DATA WHOSE FORM DEPENDS ON THE 
MODULE 


I PERFORMS A SPECIFIED CONTROL ORDER ON AN I/O SWITCH; THE ALLOWED 
ORDERS DEPEND ON THE I/O MODULE VIA WHICH THE SWITCH IS ATTACHED 
(REFER TO THE I/0 MODULE WRITE UPS) 


1 EXAMPLES OF tty_ CONTROL ORDERS: set_delay, set_editing chars, 
quit_ eee hangup 


1 EXAMPLE OF vfile_ CONTROL ORDER: read_position (RETURNS THE 
ORDINAL POSITION (0, 1, 2...) OF THE NEXT RECORD/BYTE AND 
THE END OF THE FILE) 
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AN EXAMPLE USING iox 


print file: proc; 


del iox_$attach_name.entry (char (*), ptr, char (*), ptr, fixed bin (35)); 
del iox ~$detach_ ioeb entry (ptr, fixed bin (35)); 
del iox $open entry (ptr, fixed bin, bit (1) unaligned, fixed bin (35)); 
del iox $close entry (ptr, fixed bin (35)); 
del iox $put_chars entry (ptr, ptr, fixed bin (21), fixed bin (35)); 
del iox $read_record entry (ptr, ptr, fixed bin (21), fixed bin (21), 
fixed bin (35)); 
del iox_$read_length entry (ptr, fixed bin (21), fixed bin (35)); 
del 10x $get_line entry (ptr, ptr, fixed bin (21); fixed bin (21), 
fixed bin (35)); ~ 
del 1o0x_$control entry (ptr, char (*), ptr, fixed bin (35)); 
del 10x ~$user_ output ext ptr; 
del iocb ptr ptr init (null ()); 
del code fixed bin (35) init (0); 
del com_err_ entry options (variable); 
del ME char (10) static init ("print_ file") options (constant); 
del LF char (1) static options (constant) init (" 
a Ee 
del 1 info, 
2 next_ position fixed bin (34), 
2 last_position fixed bin (34); 
del buffer char (buf_len) based (buf_ ptr); 
del) vuf_len fixed bin (21); 
del ouf ptr ptr init ( nuli() ); 
del rec_len fixed bin (21); 
del 1. fixed bin; 
del (null, addr) builtin; 
del cleanup condition; 


on cleanup call WRAPUP; 


call iox_$attach_name ("sw", iocb ptr, "vfile sample file", null (), code); 
if code “= 0 ian 
then call WRAPUP; 

3 
call iox_$open (ioeb_ ptr, 4, "0"b, code); 
if code “= 0 
then call WRAPUP; 


call iox_ $control (iocb_ptr, "read position", addr( info), code); 
if code “= 0 
then call WRAPUP; 


call iox $read_length (iocb ptr, rec_len, code); 
if code “= 0 
then call WRAPUP; 


buf_len = rec_len + 40; 
allocate buffer set (buf _ ptr); 
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AN EXAMPLE USING iox 


do i= 1 to proud pesard en, ee 
call iox tres record (Cio ptr, buf_ptr, buf_len, rec a, rege) ; 
if code “= 0 Osh weP 
then eal. WRAPUP; 
substr (buffer, rec_ len+1, 1) = LF; 
call iox_$put_ chars (iox _$user_ output, buf_ dens rec_len + 1, code); 
if code “= 0 
then call WRAPUP; 

end /* do i */; 


call WRAPUP; 


WRAPUP: proc; 


if code “= 0 
then call com_err_ (code, ME); 


if iocb, ptr “= null () 
then do; 
call iox_$close (iocb ptr, code); 
call iox_$detach_ioeb (iocb ptr, code); 
end /* then do */; 


if buf_ptr “= null () 
then free buf _ptr => buffer; 


goto FINIS; 

end /* WRAPUP #*/; 
FINIS: 

end /* print file */; 


r 14:40 0.259 32 


! vfs sample file 
type: sequential 
records: 5 
r 14:41 0.261 19 


! print file 
This is record number 1 
THIS IS RECORD TWO 
Hi, I'm the third record 
Would you believe four? 
I am the last record 
r 14:41 0.288 7 
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Topic IX THE IOA_ SUBROUTINE Topic IX 


OBJECTIVES: 


Uron completion of this topic, students should be able to: 


1. Write simple character strinss to the user's terminal. 


2. Use iteration and conditional avaluation to form complex 
output strinss for display on the terminal. 


3. Write to a file via an I/O switch. 


4. Write to a file usins the Multics Virtual Memory. 
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CHARACTERISTICS 


@® USED FOR FORMATTING A CHARACTER STRING FROM FIXED-POINT NUMBERS, 
FLOATING=POINT NUMBERS, CHARACTER STRINGS, BIT STRINGS, AND POINTERS 


] THE CHARACTER STRING IS FORMATTED ACCORDING TO THE CONTROL 
CHARACTERS EMBEDDED IN AN ‘ioa_' CONTROL STRING 


[I THE ENTIRE PROCEDURE IS SIMILAR TO FORMATTING OUTPUT IN PL/I OR 
FORTRAN 


@® SEVERAL ENTRY POINTS ARE PROVIDED IN 'ioa_' TO PROVIDE VARIOUS OPTIONS 


1 SINCE ALL OF THE ENTRY POINTS CAN BE CALLED WITH A VARIABLE 
NUMBER OF ARGUMENTS, THEY ALL MUST BE DECLARED ‘entry 
options( variable) ' 


1 ‘'ioa_' NORMALLY APPENDS A NEWLINE CHARACTER TO THE END OF THE 
STRING CREATED . 


I A CORRESPONDING ENTRY POINT IS PROVIDED FOR EVERY STANDARD ENTRY 
POINT WHICH SPECIFIES THAT "NO NEWLINE" IS TO BE APPENDED 
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ENTRY POINTS 


@® ENTRY POINTS IN ioa_ ARE: 


I ioa_, ioa_$nnl 
1 call ioa_ (control_string, argi, ..., argN); 


I FORMAT THE INPUT DATA ACCORDING TO THE CONTROL STRING, AND 
WRITE THE RESULTING STRING ON ‘user_output' 


1 ioa $ioa_stream, ioa_ $ioa_stream_nnl 


J call ioa $ioa_stream (switchname, control_string, argi, ..., 
argN); 


] FORMAT THE RESULTING STRING AS ABOVE, BUT THE STRING IS THEN 
WRITTEN TO AN I/O SWITCH SPECIFIED BY THE SWITCHNAME ARGUMENT 


I ioa_ $ioa_switch, ioa_ $ioa_switch_nnl 


q cake ioa_$ioa_ switch (iocb ptr, control string, argli, ..., 
argN); 


I IDENTICAL TO THE ioa | $ioa_stream AND ioa $ioa_ $stream_nnl ENTRY 
POINTS EXCEPT THAT THE I/0 SWITCH IS DESIGNATED BY A POINTER 
TO ITS IOCB, RATHER THAN BY SWITCHNAME (HENCE, THESE ENTRY 
POINTS ARE A BIT MORE EFFICIENT) 
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ENTRY POINTS 


1 ioa_$rs, ioa $rsnnl 


) call ioa_ $rs (control string, ret_string, ret_length, argi, 
eee, argN); 


— EDITING OCCURS AS IN THE ABOVE CALLS, BUT INSTEAD OF BEING 
WRITTEN TO AN I/0 SWITCH, THE STRING IS PASSED BACK TO THE 
CALLER IN A CHARACTER STRING VARIABLE 


I THE CHARACTER STRING VARIABLE PROVIDED BY THE CALLER MAY BE 
VARYING OR NONVARYING, ALIGNED OR UNALIGNED AND OF ANY LENGTH 


] THE LENGTH OF THE CREATED STRING IS ALSO RETURNED 


I ioa_$rsnp, ioa_$rsnpnnl 


1 ‘THESE ARE IDENTICAL TO THE ioa $rs AND ioa_$rsnnl ENTRY POINTS 
EXCEPT THAT THEY DO "NO PADDING" OF A STRING RETURNED INTO A 
NONVARYING CHARACTER STRING 
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CONTROL STRING 


@ A NON-VARYING CHARACTER STRING CONSISTING OF TEXT TO BE COPIED AND/OR 
ioa_ CONTROL CODES 


@ ioa_ CONTROL CODES ARE ALWAYS IDENTIFIED BY A LEADING CIRCUMFLEX 
(*) CHARACTER, AND SPECIFY THE TYPE OF EDITING TO BE DONE FOR THEIR 
CORRESPONDING argi 


@ PROCESSING BY ioa_ BEGINS BY SCANNING THE CONTROL STRING UNTIL A 
CIRCUMFLEX IS FOUND, OR THE END OF THE STRING IS REACHED 


[ ANY TEXT (INCLUDING BLANKS) PASSED OVER IS COPIED TO THE OUTPUT 
STRING 


I] CONTROL CODES ARE INTERPRETED, GENERALLY BY EDITING THE NEXT 
argi INTO THE OUTPUT STRING IN A FASHION DICTATED BY THE CONTROL 
CODE 
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CONTROL STRING 


CONTROL CODE ACTION 

“d “nd ; Edit a fixed-point decimal integer 

“i “ni same as “d (FOR COMPATIBILITY WITH FORTRAN) 
“a. ne Edit a floating-point number 

ag 
“e “ne Edit a floating-point number in exponential 
form s 

*“o “no : Edit a fixed-point number in octal 

“w “nw Edit a full machine word in octal 

“a “na Edit a character string in ASCII 

“b “nb Edit a bit string 

“n.db 
.db 

“p Edit a pointer 

“TM Insert formfeed character(s) 

“f “ns Insert newline character(s) 

*- “ne Insert horizontal tab character(s) 

“x “nx Insert space character(s) 

ae Insert circumflex character(s) 

“s “ns Skip argument(s) 

“( “ne Start an iteration loop 

*) | End an iteration loop 

me Start an if/then/else or case selection group 
| Limit the scope of a “[ 

a Use as a clause delimiter between “[{ “] 

“nt “n.mt Insert enough space to reach column n 
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CONTROL STRING 


@ WHEN n AND/OR d APPEAR IN A CONTROL CODE, THEY GENERALLY REFER TO A 
FIELD WIDTH OR A REPETITION FACTOR (THE EXACT MEANING DEPENDS ON 
THE CONTROL CODE WITH WHICH THEY APPEAR) 


0 THE n OR d MUST BE SPECIFIED AS UNSIGNED DECIMAL INTEGERS, OR AS 
THE LETTER "v", IN WHICH CASE, THE NEXT argi ARGUMENT (WHICH 
MUST BE FIXED BINARY) IS USED TO OBTAIN THE ACTUAL VALUE 


@® IF NO FIELD WIDTH IS SPECIFIED, ioa_ USES A FIELD LARGE ENOUGH TO 
CONTAIN THE DATA TO BE EDITED 


@ IF TOO SMALL A FIELD WIDTH IS poner ee ioa_ IGNORES THE WIDTH AND 
SELECTS AN APPROPRIATE WIDTH 


@ NUMERIC CONTROL CODES TAKE ANY PL/I NUMERIC DATA TYPE, INCLUDING A 
NUMERIC CHARACTER STRING, AND USE STANDARD PL/1 CONVERSION ROUTINES 
IF NECESSARY 


@ ARGUMENTS THAT ARE EDITED INTO THE CONTROL STRING MAY BE ARRAYS 


I THE ELEMENTS ARE TREATED SEPARATELY IN ROW MAJOR ORDER 
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CONTROL STRING 


@® THE FOLLOWING EXAMPLES ILLUSTRATE MANY, BUT NOT ALL, OF THE FEATURES 
OF THE ioa._ SUBROUTINE. 


THE SYMBOL B&B IS USED TO REPRESENT A SPACE 


IN THE PLACES WHERE THE SPACE IS SIGNIFICANT 


Source: 


Result: 


source: 


Result: 


Source: 


Result: 
source: 
‘Result: 
Source: 
Result: 


Source: 


Result: 


Source: 


Result: 


Source: 


Result: 


call ioa_("This is “a the third of “a","Mon" ,"July") ; 


This is Mon the third of July 


call ioa ("date “d/*d/*d, time “d:*d",6,20,74, 2014, 36); 
date 6/20/74, time 2014: 36 


call ioa_ ("overflow at “p",ptr); 


overflow at 271:4671 


call ioa_("°2(°2(°w *)°/*7) " wi,w2,w3,w4); 
112233445566 000033004400 

000000000001 7777777T7T7T7T 
bit="110111000011"b; 

call ioa_("“vxoct=*.3b hex=*.4b",6,bit ,bit); 


bbb6bbboc t=6703 bhex=DC3 


call ioa (""f “e “f *5.2f",1.0,1, 1e-10,1); 


1. b1.e0 b1.e-10 61.00 


call ioa ("°(7d *)",1,2,56,198,456.7, 3e6); 

1 2 56 198 456 3000000 

abs sw=0; 

call ioa $rsnnl("*v( Absentee user ~)*a “a logged out.", 
out_str,out_cnt,abs_ sw,"LeValley" ,"Shop") ; 


out _cent=25; 
Out_str="LeValley Shop logged out." 
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Source: 


Result: 


Source: 


Result: 


Source: 


Result: 


Source: 


Result: 


Source: 


Result: 


Source: 


Result: 


Source: 


Result: 


Source: 
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CONTROL STRING 


abs sw=l; /* Using same call to ioa $rsnni #/ 
call ioa_$rsnnl("“v( Absentee user ~)*a “a logged out.", 
out_str,out_cnt,abs “sw,"LeValley"," Shop") ; 


out_ent=39; 

out_ str="Absentee user beveviey Shop logged out." 
del a(2,2)fixed bin init(1,2,3,4); 

call ioa_(""d*s “d “w",a); 


1 3 000000000004 


del b(6:9)fixed bin init(6,7,8,9); 
eall ioa_("*v(*3d")",dim(b,1),b); 
6 7 8 9 
sw="0"b; 
call ioa_ ("a=“d “[b="d*;%s*] c=%d",5,sw,7,9); 
az5 es9 
swe "1 "b; 


call ioa_ ("a=“d “[b="d*;“s*] c=*d",5,sw,7,9); 


azs5 b=7 es9 
ename="foo"; 


("Error in segment 
(dir “=">"), ename); 


dirs">"; 


call ioa_ <a 12) a dares 


Error in segment >foo 


dir=">foo"; ename="bar"; 
call ioa_ ("Error in segment te to] "a". dir, 
(dir “= ">"), ename); 


Error in segment >foo>bar 


option=2; /* Assume following call. is on one line */ 
call ioa_ ("Insurance option selected: 
“{no fault*;bodily injury*;propertydamage*]", option); 


F15C 


CONTROL STRING 


YOU ARE NOW READY FOR WORKSHOP 
#6 
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Topic X MULTICS STORAGE SYSTEM SUBROUTINES Topic X 


OBJECTIVES: 


Upon completion of this topic, students should be able to: 


1. 


Add and remove entries to and from the Multics Storage 
System. 


Manipulate pathnames usins Multics subroutines. 
Obtain status information on entries in the storase system. 


Chanse the eetees control lists (ACLs)? of various entries in 
the storage system. 


Use Multics subroutines to obtain information about a user’s 
home, working, and process directories. 


Discuss the access required to perform any of the above 
operations. 
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THE MULTICS STORAGE SYSTEM 


@ THE STORAGE HIERARCHY IS ORGANIZED INTO AN INVERTED TREE STRUCTURE 


] THIS TREE IS MADE UP OF DIRECTORY SEGMENTS, SEGMENTS, MULTI-SEGMENT 
FILES AND LINKS 


@ FOR NON-DIRECTORY SEGMENTS: 


I SUBJECT TO THE THREE ACCESS CONTROL MECHANISMS, THE USER IS FREE 
TO CREATE, DESTROY, AND MODIFY THE CONTENTS OF SEGMENTS 


] USER-CREATED SEGMENTS NORMALLY "RESIDE" IN THE RING OF THE CREATOR. 
THE USER IS FREE TO ACCESS SUCH SEGMENTS WITHOUT HAVING TO "CROSS" 
ANY RING BOUNDARIES 


@ FOR DIRECTORY SEGMENTS: 


1 THE USER MAY CREATE, DESTROY, AND MODIFY DIRECTORY SEGMENTS, BUT 
NOT DIRECTLY (THEY ARE PROTECTED AGAINST DIRECT ACCESS VIA THE 
RING MECHANISM) 


1 ALLOWING USERS TO MANIPULATE DIRECTORY SEGMENTS DIRECTLY WOULD 
BE INVITING CHAOS, SINCE DIRECTORY SEGMENTS DETERMINE THE INTEGRITY, 
SECURITY AND CONSISTENCY OF THE HIERARCHY 


I DIRECTORY SEGMENTS ARE PLACED IN RING O AND USERS ULTIMATELY 
ACCESS SUCH SEGMENTS BY USING A SYSTEM=-PROVIDED GATE PROCEDURE 
CALLED hes 
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THE MULTICS STORAGE SYSTEM 


@® THE hes SUBROUTINE 


I PROVIDES VARIOUS ENTRY POINTS FOR MANIPULATION OF THE STORAGE 
SYSTEM AND VIRTUAL ADDRESS SPACE 


IT ALL ACCESS TO THE STORAGE SYSTEM IS ACCOMPLISHED VIA THIS GATE 
PROCEDURE 


@® THE STORAGE MANIPULATION SUBROUTINES COVERED IN THIS COURSE ARE 
SUMMARIZED BELOW: 
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SUMMARY OF DISCUSSED SUBROUTINES 


CREATING STORAGE SYSTEM ENTITIES 


hes $append_branch 
hes, ; $append_ branchx 
hes_ | $append_ link 
hes_ ; $create_ branch_ 
hes_ | $make_seg 


DELETING STORAGE SYSTEM ENTITIES 


delete $path 
delete _$ptr 


OBTAINING STATUS INFORMATION 


hes $status_ 

hes_  $status_ long 
hes. ; $status_ minf 
hes_  $status_ mins 


SECURITY 


liek group_id 

get_group id _$tag_ star 
hes $add_ acl_ entries 

hes $add_ dir acl entries 
hes $delete_ acl _ ‘entries 
hes $delete_ dir_ acl_entries 
hes $fs_ get_ mode 

hes $list_ acl 

hes $list. dir acl 

hes | ; $replace_ ‘acl 

hes _ | $replace_ dir_acl 


“WORKING, DEFAULT, AND PROCESS DIRECTORIES 


change default wdir_ 
change_ wdir_ 
get_default_wdir_ 
get_pdir_ 

get wair_ 
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SUMMARY OF DISCUSSED SUBROUTINES 


MANIPULATING PATHNAMES 


absolute _pathname_ 

ab solute _ ~ pathname_ $add_ suffix 

ex pand_ pathname_ 

ex pand_ pathname | $add_suffix 

ex pand_ pathname .$component 

ex pand_ pathname_ $component add_ suffix 
get shortest _path_ 

pathname_ 

pathname_ $ component 

pathname __ $ component check 


NAMING AND MOVING DIRECTORY ENTRIES 


hes $chname file 
hes $chname_ seg 
hes $fs_move file 
hes $fs_move_seg 


AFFECTING LENGTH OF ENTRIES 


adjust_bit_count_ 
hes ; $set_ be 

hes $truncate_file 
terminate file_ 


MANIPULATING THE ADDRESS AND NAME SPACES 


hes $fs_get_path_name 
he s_ $fs_ get_ ref name 
hes, Sts: get_ seg “ptr 
he s_ ; $make_ seg 
initiate Tite. 

term _$refname_ 

term _ _$seg_ptr 

tern ~$single_ refname 
term _ $term_ 

term _$un snap 
terminate_file_ 
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CREATING STORAGE SYSTEM ENTITIES 


This Page Intentionally Left Blank 
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CREATING STORAGE SYSTEM ENTITIES 


ce 
[Gan use to eeate segments ——SSSCSCSC~C~iC XX | 


Obeys initial acl 
a 
LL cP 
| Can set ring brackets 


a ES a 
[eanserbicoune SSCS SCY 


Can be told to chase links 
Can move misled to directory og ee 


ae ae 
er 


deal info structure 


[iter red women eT 
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CREATING STORAGE SYSTEM ENTITIES 


ic) 
# call hes $make_ seg (dir_name, entryname, ref_name, mode, 
seg ptr, code); 


# call hes $append_branch (dir_name, entryname, mode, code); 


@® call hes $append_branchx (dir name, entryname, mode, LG ward 
~user—id>tir_ _SW, copy sw, bit_count, code); 


Not To Be Reproduced 10-7 F15C 


CREATING STORAGE SYSTEM ENTITIES 


@ call hes $create_ branch_ (dir_name, entryname, info ptr, code); 


1 info _ptr POINTS TO THE FOLLOWING STRUCTURE: 


/* BEGIN INCLUDE FILE - - - create _branch_info.incl.pl1 
- - - created January 1975 */ 


/* this include files gives the argument structure for 
create_branch_ */ 


del 1 create _branch_info aligned based, 
2 version fixed bin, 
/* set this to the largest value given below */ 
2 switches unaligned, 
3 dir sw bit (1) unaligned, 
/*® if on, a directory branch is wanted *#/ 
3 copy _sw bit (1) unaligned, 
/* if on, initiating segment Will be done by copying */ 
3 chase_sw bit (1) unaligned, 
/* if on, if pathname is a link, it will be chased */ 
3 priv_upgrade sw bit (1) unaligned, 
/*” privileged creation (ring 1) of upgraded object */ 
3 parent_ac_ sw bit (1) unaligned, 
/* if on, use parent's access class for seg or 
dir created */ 
3 mbz1 bit (31) unaligned, 
/* pad to full word */ 
mode bit (3) unaligned, 
/* segment or directory for acl for userid */ 
mbz2 bit (33) unaligned, 
/* pad to full word */ 
rings (3) fixed bin (3), 
/* branch's ring brackets *#/ 
userid char (32), 
/* user's access control name *#/ 
bitent fixed bin (24), 
/*® bit count of the segment *#/ 
quota fixed bin (18), 
/* for directories, this am't of quota will be moved 
to it */ 
2 access class bit (72); 
/* is the access class of the body of the branch *#/ 


mw NO NYO WO NN NM 


/* The following versions are implemented Ue ee tae 
/* (Changes to structure require defining new static 
initialized variable) *#/ 


del create_branch_version_1 static fixed bin init (1); 
/* branch info valid through access class field */ 
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CREATING STORAGE SYSTEM ENTITIES 


@ NOTES: 


] FOR BOTH hes $make_seg AND hes $append_branch: 
] THE BIT COUNT AND COPY SWITCH ARE SET TO 0 


] THE SPECIFIED MODE IS SET FOR Person_id.Project_id.* 


1 FOR hes $make_seg, hes $append_branch AND hes $append_branchx THE 
MODE IS SPECIFIED AS FOLLOWS: 


1 FOR SEGMENTS: 


read the 8=bit is 1 (01000b) 
execute the 4=bit is 1 (00100b) 
write the 2-bit is 1 (00010b) 


1 FOR DIRECTORIES: 


Status the 8-bit is 1 (01000b) 
modify the 2=-bit is 1 (00010b) 
append the 1-bit is 1 (00001b) 


1 THE MODE FOR hes $create branch IS SPECIFIED IN SIMILAR MANNER, 
USING ONLY 3 BITS oe a : 


Oe ed 
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CREATING STORAGE SYSTEM ENTITIES 


/* BEGIN INCLUDE FILE ... access mode values.inel.pl1 


Values for the "access mode" argument so often used in hardcore 
James R. Davis 26 Jan 81 MCR 4844 
Added constants for SM access 4/28/82 Jay Pattin 


#/ 

del (N_ACCESS init ("000"b), 
R_ACCESS init ("100"b), 
E_ACCESS init ("010"b), 
W_ACCESS init ("001"b), 
RE_ACCESS init ("110"b), 
REW_ACCESS init ("111"b), 
RW_ACCESS init ("101"b), 
S_ACCESS init ("100"b), 
M_ACCESS init ("010"b), 
A_ACCESS init ("001"b), 
SA_ACCESS init ("101"b), 
SM_ACCESS L1G OCT V1O "Ds, 
SMA ACCESS init (111"b)) 

bit (3) internal static options (constant); 

del (N_ACCESS BIN init (00000b), 
R_ACCESS_ BIN init (01000b), 
E_ACCESS_BIN init (00100b), 
W_ACCESS BIN ~ init (00010b), 
RW_ACCESS BIN init (01010b), 
RE_ ACCESS BIN init (01100b), 
REW_ACCESS BIN init (01110b), 
S_ACCESS_BIN init (01000b), 
M_ ACCESS BIN init (00010b), 
A_ACCESS BIN init (00001b), 
SA_ACCESS BIN init (01001b), 
SM_ACCESS BIN init (01010b), 
SMA_ACCESS BIN init (01011b)) 


fixed bin (5) internal static options (constant); 


/* END INCLUDE FILE ... access mode values.incl.pl1 */ 
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CREATING STORAGE SYSTEM ENTITIES 


@ hes $append_ link 
J call hes $append_link (dir_name, entryname, path, code); 
] CREATES A LINK IN SPECIFIED DIRECTORY 


] LINK'S TARGET NEEDN'T EXIST AT CREATION TIME (CODE OF ZERO STILL 
RETURNED) 


1 APPEND PERMISSION REQUIRED ON CONTAINING DIRECTORY 
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DELETING SEGMENTS, DIRECTORIES, AND LINKS 


® delete 


1 HAS TWO ENTRY POINTS 


I delete $path 


0 GIVEN AN ENTRYNAME, DELETES SEGMENTS, MSFs, DIRECTORIES, 
AND LINKS 


I delete $ptr | 
0 GIVEN A POINTER, DELETES SEGMENTS ONLY 


] call delete $path (dir_name, entryname, switches, caller, code); 


f call delete $ptr (seg ptr, switches, caller, code); 


] DIRECTORY TO BE DELETED NEED NOT BE EMPTY 


1 UNSNAPS ANY LINKS THIS PROCESS HAS SNAPPED TO THE OBJECTS DELETED 


I NOTE: delete CAN'T PREVENT DISASTER WHEN ONE PROCESS DELETES 
ANOTHER'S SHARED SEGMENT 


] THE 6 BIT INPUT VARIABLE 'switches' MAKES THIS SUBROUTINE EXTREMELY 
FLEXIBLE 


I SEE THE SUBROUTINES MANUAL FOR DETAILS OF THE 6 SWITCHES 
(force_sw, question_sw, directory sw, segment _sw, Link sw, 
chase_ sw) 
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OBTAINING STATUS INFORMATION 


@ THE FOLLOWING 4 ENTRY POINTS RETURN STATUS INFORMATION FOR A DIRECTORY 
ENTRY (LISTED IN ORDER OF INCREASING COMPLEXITY) 


=> hes $status_mins 
— hes _$status_minf 
hes $status_ 


‘hes $status_long 


J ALL THE ABOVE ENTRY POINTS HAVE A CURIOUS ACCESS REQUIREMENT 


] INFORMATION IS RETURNED IF CALLER HAS STATUS ON THE CONTAINING 
DIRECTORY, OR NON-NULL ACCESS ON THE ENTRY 


1 ENTRYNAMES ARE NOT RETURNED UNLESS THE CALLER HAS STATUS ACCESS 
ON THE CONTAINING DIRECTORY 


THE STATUS ENTRY POINTS, DIRECTORIES AND MULTI-SEGMENT FILES 
K I | : 


I THE ONLY DISTINGUISHING ATTRIBUTE IS THE BIT COUNT 


1 BIT COUNT = 0 FOR A DIRECTORY 
I BIT COUNT = NUMBER OF COMPONENTS FOR A MSF 
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OBTAINING STATUS INFORMATION 


@ hes $status_minf 


J call hes $status_minf (dir _name, entryname, chase_ sw, 
type, bit count, code); 


1 RETURNS BIT COUNT AND ENTRY TYPE OF ENTRY, GIVEN A PATH 
I + TYPE OF ENTRY: 
O MEANS link 


1 MEANS segment 
2 MEANS msf OR directory 


1 OFTEN USED WHEN TRYING TO DISTINGUISH BETWEEN DIR AND MSF 


@ hes $status_ mins 


1 call hes $status_mins (seg ptr, type, bit cout, code): 


I RETURNS BIT COUNT AND ENTRY TYPE OF A SEGMENT GIVEN A POINTER 


THE SEGMENT 


Not To Be Reproduced 10-14 


TO 


F15C 


OBTAINING STATUS INFORMATION 


@ hes $status_ 


2 call hes $status_ (dir. name, entryname, chase _sw, status ptr, 
status_area_ptr, code); | 


1 RETURNS INFORMATION ABOUT A SEGMENT, DIR, MSF, OR LINK: 


1 INFORMATION INCLUDES ENTRY TYPE, “DATE TIME CONTENTS LAST 
MODIFIED, DATE TIME LAST USED, NUMBER OF RECORDS USED, USER'S 
RAW MODE, USER'S EFFECTIVE MODE AND ENTRYNAMES (NO BIT COUNT) 


J CALLER MUST PROVIDE 
] POINTER TO CALLER-ALLOCATED INFO STRUCTURE 


I POINTER TO CALLER-DESIGNATED AREA TO CONTAIN "names" (IF NULL, 
NO NAMES RETURNED) 
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OBTAINING STATUS INFORMATION 


/* --- BEGIN include file status structures.incl.pli --- */ 


/* Revised from existing include files 09/26/78 
by C. D. Tavares #/ 


/* This include file contains branch and link structures 
returned by hes $status_ and hes $status_long. */ 


del 1 status_branch aligned based (status_ptr), 
2 short aligned, 

3 type fixed bin (2) umaligned unsigned, 
/* seg, dir, or link #/ 

3 nnames fixed bin (16) unaligned unsigned, 
/* number of names */ 

3 names relp bit (18) unaligned, 
/* ‘see entry names del */ 

3 dtem bit (36) unaligned, 
/* date/time contents last modified */ 

3 dtu bit (36) unaligned, 
/* date/time last used */ 

3 mode bit (5) unaligned, 
/* caller's effective access */ 

3 raw mode bit (5) unaligned, 
/* caller's raw "rew" modes ¥/ 

3 padi bit (8) unaligned, 

3 records used fixed bin (18) unaligned unsigned, 
/* number of NONZERO pages used */ 


/* Limit of information returned by hes $status_ */ 


2 long aligned, 

3 dtd bit (36) unaligned, 

/* date/time last dumped */ 
3 dtem bit (36) unaligned, 
/* date/time branch last modified */ 

3 lvid bit (36) unaligned, 

/* logical volume ID *#/ 
current length fixed bin (12) unaligned unsigned, 

/* number of last page used */ 
bit count fixed bin (24) unaligned unsigned, 

/*® reported length in bits */ 
pad2 bit (8) unaligned, 
copy_switch bit (1) unaligned , 

/*~copy switch */ 
tpd switch bit (1) unaligned, 

/*® transparent to paging device switch */ 
mdir_ switch bit (1) unaligned, 

/* is a master dir */ 
damaged switch bit (1) unaligned, 

/* salvager warned of possible damage */ 
3 synchronized switch bit (1) unaligned, 

/# int od 


wo WD Wo WwW WwW 


Cc 
of 
if) 
a 
~ Ot 
a 
sie 
QO 
Wy 
ps 
rw) 
a 
tej 
1) 
fe™ 
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OBTAINING STATUS INFORMATION 


3 ring_brackets (0:2) fixed bin (6) unaligned unsigned, 
3 uid bit (36) unaligned; /* unique ID */ 
del 1 status_ link aligned based (status_ptr), 
2 type fixed bin (2) unaligned unsigned, "/* as above */ 
2 nnames fixed bin (16) unaligned un signed 
2 names _relp bit (18) unaligned, 
2 dtem bit (36) maligned, 
2 dtd bit (36) unaligned, 
2 pathname length fixed bin (17) unaligned, 
/* see pathname *#/ 
2 pathname relp bit (18) unaligned; /* see pathname */ 


del status_entry names (status_branch.nnames) 
character (32) aligned based ; 
(pointer (status area ptr, status_branch.names relp)), 
/* array of names returned */ 
Status pathname character (status _link.pathname length) 
aligned based 
(pointer (status area ptr, status_link.pathname relp)), 
/* link target path */ 
Status area_ptr pointer, 
status ptr pointer; 


del (Link initial (0), 


Segment initial (1 1), 
Dii ector y initial (2) Aa 44450 i LLd ii uci aa wveauiw 
options (constant); 


/* values for type fields declared above */ 


/* --- END include file status_structures.inel.pli --- */ 
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OBTAINING STATUS INFORMATION 


@ hes $status_long 


1 call hes $status_long (dir_name, entryname, chase sw, status_ptr, 
status_area_ptr, code); 


| RETURNS EVERYTHING hes $status_ RETURNS PLUS: 
l DATE-TIME-LAST-DUMPED (SEGS ONLY) 
J CURRENT LENGTH IN 1024-WORD UNITS (SEGS, MSFS) 
1 BIT COUNT (SEGS, MSFS) 


1 PHYSICAL VOLUME ID OF STORAGE DEVICE ON WHICH ENTRY CURRENTLY 
RESIDES 


i COPY AND DAMAGED SWITCH VALUES 
SEE THE switch_on and switch _off COMMANDS (AG92) 


f RING BRACKETS 


[ SEGMENT UNIQUE ID 
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OBTAINING STATUS INFORMATION 


® OTHER ENTRY POINTS THAT RETURN STATUS TYPE INFORMATION! 
] hes $get_author, hes $get_be_ author 
1 hes $get_max_length, hes $get_max_length_seg 
J he s_8 get_safety sw, hes $get_ safety sw_seg 


1 hes $get_link_target 


@® TO OBTAIN STATUS INFORMATION FOR ARCHIVE COMPONENTS SEE 


= 
a) 


) archive $list_components 


f archive $next_component info 


a 


COVERED IN MULTICS COURSE F15D 
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OBTAINING STATUS INFORMATION 
AN EXAMPLE 


Status: proc; 


del 1 status_branch aligned based (status_ptr), 

type fixed bin (2) unaligned unsigned, 

nnames fixed bin (16) unaligned unsigned, 

names relp bit (18) unaligned, 

dtem bit (36) unaligned, 

dtu bit (36) unaligned, 

mode bit (5) unaligned, 

raw_mode bit (5) unaligned, 

padi bit (8) umaligned, 

records used fixed bin (18) unaligned unsigned; 

del status_entry_names (status_branch.nnames) character (32) aligned 

based (pointer C(get_ system_ free_ area (), status_branch.names relp)); 

dcl pointer builtin; 

del get_system_free_area_ entry() returns(ptr); 

del status_ ptr ptr; 

del (ioa_, 

com_err_) entry options (variable); 

del hes $status_ entry (char (*), char (*), fixed bin (1), ptr, 
ptr, fixed bin (35)); 

del code fixed bin (35); 

del i; 


MMMM MM N NP fo 


allocate status_branch; 
call hes | $status_ ("> udd>MEDelass>F15C", "si", 0, status ptr, 
get_system_free area_(), code); 

if code “= 0 
then do; 

call com_err_ (code, "Status"); 

return; 

end /* then do */; 


call ioa_ ("°/si1 is a “{link*;segment”;directory”] with “d names:", 
status _branch.type + 1, status_branch.nnames) ; 
do iz 1 to status branch.nnames; 
call ioa_(" ~*a", status_entry_names(i)); 
end /* do i */; 


end /* Status */; 
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OBTAINING STATUS INFORMATION 
AN EXAMPLE 


r 15:00 0.148 19 
! Status 
si is a directory with 2 names: 
Student 01 


$1 
r 15:00 0.124 6 
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SECURITY 


@ MULTICS HAS THREE ACCESS CONTROL MECHANISMS 
J THE ACCESS CONTROL LIST MECHANISM (ACLS) 
1 THE ACCESS ISOLATION MECHANISM (AIM) 


) THE RING MECHANISM 


# hes. AND OTHER SUBROUTINES ENABLE US TO MANIPULATE THESE MECHANISMS 
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ACCESS CONTROL LISTS 


® hes $add_acl entries 


) call hes $add_acl_entries (dir _nhamée, entryname, acl ptr, 
acl_count, code); 


] ADDS OR CHANGES ("SETS") ACL ON A SEGMENT (rewn) 
0 CALLER MUST ALLOCATE AND FILL IN AN ARRAY OF STRUCTURES 


I "MATCHING" ACCESS NAMES ACCEPTABLE TO THE set_acl COMMAND ARE 
NOT ACCEPTABLE 


I SEE msf_manager_$acl_add FOR MULTI-SEGMENT FILES! 


@ hes $add_ dir acl entries 


1 call hes $add_dir_acl_entries (dir_name, entryname, acl ptr, 
acl_count, code); 


] ADDS OR CHANGES ("SETS") ACL ON DIRECTORIES (sman) 


0 SIMILAR TO hes | $add_acl_entries EXCEPT STRUCTURE MISSING 
ex tended_ mode 


COVERED IN MULTICS COURSE F15D 
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ACCESS CONTROL LISTS 


/* Begin include file -- acl_structures.incl.pli BIM 3/82 */ 
/* format: style3 */ 


declare acl_ptr pointer; 
declare acl_ count fixed bin; 
declare 1 segment_acl aligned based (acl ptr), 
2 version fixed bin, 
2 count fixed bin, 
2 entries (acl_count refer (segment_acl.count) ) 


aligned like segment acl entry; 


declare 1 segment_acl_entry aligned based, 


2 access_name character (32) unaligned, 
2 mode bit (36) aligned, 

2 extended mode bit (36) aligned, 

2 status_code fixed bin (35); 


declare 1 segment_acl_ array (acl_count) aligned like 
segment_acl_entry based (acl_ptr); 


‘declare 1 directory acl aligned based (acl_ptr), 
2 version fixed bin, 
2 count fixed bin, 
2 entries (acl_count refer (directory acl.cour 


aligned like directory acl _entry; 


declare 1 directory acl _entry based, 


2 access name character (32) unaligned, 
2 mode bit (36) aligned, 
2 status_code fixed bin (35); 


declare 1 directory acl array (acl_count) aligned like 
directory. acl_entry based (acl ptr); 


declare 1 delete _acl_entry aligned based, 


2 access name character (32) unaligned, 
2 status_code fixed bin (35); 
declare 1 delete acl based (acl ptr) aligned, 
2 version _ fixed bin, 
2 count fixed bin, 
2 entries (acl_count refer (delete acl.count) ) 


aligned like delete acl entry; 


declare 1 delete _acl_array (acl_count) aligned like 
delete _acl_entry based (acl_ptr); 


declare ACL_VERSION 1 internal static fixed bin i 
options (constant); 


/* End include file acl_structures.incl.pli */ 
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ACCESS CONTROL LISTS 


@ hes $delete_acl_ entries 


1 call hes $delete_acl_entries (dir_name, entryname, acl ptr, 
acl _ count, code); 


I DELETES ONE OR MORE ENTRIES FROM A SPECIFIED SEGMENT'S ACL 
I USES A STRUCTURE ALLOCATED BY CALLER 


I "MATCHING" ACCESS NAMES ACCEPTABLE TO THE delete_acl COMMAND 
ARE NOT ACCEPTABLE TO hes $delete_acl_entries 


] SEE msf_manager $acl_delete FOR MULTI-SEGMENT FILES] 


@® hes $delete dir_acl_entries 


] call hes $delete dir_acl_entries (dir_name, entryname, acl_ptr, 
acl_ count, code); 


] DELETES ONE OR MORE ENTRIES FROM A SPECIFIED DIRECTORY'S ACL 


I OTHERWISE SIMILAR TO hes $delete acl entries 


COVERED IN MULTICS COURSE F15D 
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ACCESS CONTROL LISTS 


#@ hes $list_acl 


0 call hes $list_acl (dir_name, entryname, area ptr, 


area_ret_ptr, acl_ptr, acl_count, code); 


1 RETURNS ALL OR PART OF A SEGMENT'S ACLIN A "segment_acl' STRUCTURE 
(SAME STRUCTURE AS USED BY hes | Sadd_ acl entries) 


) THERE ARE TWO DIFFERENT WAYS TO USE THIS ENTRY POINT: 


I. ULE 
I 


— ee | 


ENTIRE ACL REQUIRED: 


SET "area_ptr™ NON-NULL AND EXPECT BACK "acl_count" AND 
“area _ret_ptr" 


SUBROUTINE ALLOCATES AN ARRAY OF STRUCTURES 


JUST SOME MODE ENTRIES REQUIRED: 

SET "area_ptr" NULL 

USER ALLOCATES AN ARRAY OF PARTIALLY FILLED IN STRUCTURES 
PASS A PTR TO THIS ARRAY (acl_ptr) 

MODES AND CODES WILL HAVE BEEN FILLED IN UPON RETURN 


a 


@ hes $list_dir_acl 


J call hes $list_dir_acl (dir_name, entryname, area ptr, 


area_ret_ptr, acl_ptr, acl count, code); 


1 RETURNS ALL OR PART OF A DIRECTORY'S ACL 


I SIMILAR TO hes $list_acl EXCEPT USES dir_acl STRUCTURE 
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ACCESS CONTROL LISTS 


@ hes $replace acl 


J call hes $replace acl (dir name, entryname, acl_ptr, acl_count, 
no_sysdaemon_sw, code); 


- 


I REPLACES ENTIRE ACL FOR A SEGMENT WITH A USER-SUPPLIED ONE 
I USES SAME STRUCTURE AS hes $add_acl_entries AND hes $list acl 
0 CAN (OPTIONALLY) ADD "rw" FOR *.SysDaemon.* 


1 CAN BE MADE TO DELETE ENTIRE ACL (IF acl_count=0) 


@ hes $replace dir acl 


J call hes $replace_dir_acl (dir_name, entryname, acl ptr, 
acl_ count, no_sysdaemon_sw, code); 


I REPLACES ENTIRE ACL FOR A DIRECTORY 


J USES SAME STRUCTURE AS hes _$‘dd_dir_acl_entries AND 
hes $list_dir_acl 


2 CAN (OPTIONALLY) ADD "sma" FOR * .SysDaemon.* 


0 CAN BE MADE TO DELETE. ENTIRE ACL 
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ACCESS CONTROL LISTS 


#@ hes $fs_get_mode 
] call hes $fs_get_mode (seg ptr, mode, code); 
I RETURNS THE EFFECTIVE ACCESS MODE (rew) OF THE CALLER ON A SPECIFIED 
SEG MENT 


0 TAKES INTO ACCOUNT ACL, RING BRACKETS AND CURRENT VALIDATION 
LEVEL 


I NOTE: SINCE A POINTER IS PASSED, SEGMENT MUST HAVE BEEN MADE 
KNOWN, WHICH IMPLIES USER HAS NON-NULL ACCESS 


@® get_group_id_ 
1 user_id = get_group_id_ (); 


I RETURNS IN A char(32) nonvarying Personid.Projectid.tag 


® get group id $tag_star 
1 user_id = get_group_id $tag_star (); 


I RETURNS Personid.Projectid.*# 
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WORKING, DEFAULT, AND PROCESS DIRECTORIES 


@® change wdir_ 
] call change_wdir_ (path, code); 
I CHANGES THE WORKING DIRECTORY TO THE SPECIFIED DIRECTORY 
I REQUIRES ABSOLUTE PATHNAME 


] COMMAND INTERFACE: cwd 


® get _wdir_ 


1 working dir = get _wdir_ (); 


I RETURNS THE ABSOLUTE PATHNAME OF THE USER'S CURRENT WORKING 
DIRECTORY IN A char(168) nonvarying 


0 COMMAND INTERFACE: pwd 
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WORKING, DEFAULT, AND PROCESS DIRECTORIES 


@® get _pdir_ 
0 process dir = get_pdir_ (); 


1 THIS FUNCTION RETURNS THE ABSOLUTE PATHNAME OF THE USER'S PROCESS 
DIRECTORY IN A char(168)nonvarying 


0 COMMAND INTERFACE: pd 


@ get default wdir_ 
1 default_wdir = get_default_wdir_ (); 


1 RETURNS THE ABSOLUTE PATHNAME OF THE CALLER'S DEFAULT WORKING 
DIRECTORY IN A char(168) nonvarying 


COMMAND INTERFACE: pdwd 
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WORKING, DEFAULT, AND PROCESS DIRECTORIES 


@ change default wdir_ 
1 call change _default_wdir_ (path, code); 


] CHANGES THE USER'S CURRENT DEFAULT WORKING DIRECTORY TO THE 
DIRECTORY SPECIFIED 


I COMMAND INTERFACE: ecdwd 


Not To Be Reproduced 10-31 F15C 


MANIPULATING PATHNAMES 


@® expand _pathname_ 
call expand pathname (pathname, dirname, entryname, code); 
I CONVERTS A RELATIVE OR ABSOLUTE PATHNAME INTO A DIRECTORY PATHNAME 
AND AN ENTRYNAME 


I COVERED IN TOPIC 5 


@ expand pathname $add_suffix 


cali expand pathname $add_suffix (pathname, suffix, dirname, 
entryname, code); 


1 SAME AS expand pathname _, BUT ALSO ADDS A SPECIFIED SUFFIX ONTO 
THE ENTRYNAME, IF THAT SUFFIX IS NOT ALREADY PRESENT 


@ expand pathname $component 


J call expand_pathname_$component (pathname, dirname, entryname, 
componentname, code); 


1 EXPANDS A >RELATIVE OR ABSOLUTE PATHNAME INTO A DIRECTORY NAME, 
AN ARCHIVE NAME, AND AN ARCHIVE COMPONENT PORTION (OR INTO A 
DIRECTORY NAME AND ENTRYNAME PORTION IF NO COMPONENT NAME IS 
PRESENT ) 
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MANIPULATING PATHNAMES 


expand_pathname $component_add_ suffix 


1 call expand_pathname $component_add_ suffix (pathname, suffix, 
dirname, entryname, componentname, code); 


1 SAME AS expand pathname $component, BUT ALSO ADDS A SPECIFIED 
SUFFIX TO EITHER THE ENTRYNAME OR THE COMPONENT NAME, IF NOT 
ALREADY PRESENT 


absolute pathname 


J call absolute pathname (pathname, full_pathname, code); 


absolute pathname $add_suffix 


0 call absolute pathname_ $add_ suffix (pathname, suffix, 
full_pathname, code); 


I] SAME AS absolute_pathname_, BUT ALSO ADDS A SPECIFIED SUFFIX IF 
THAT SUFFIX IS NOT ALREADY PRESENT 
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MANIPULATING PATHNAMES 


@® get shortest path_ 


1 shortest_path = get_shortest_path_ (original_path); 


® pathname_ 
1 path = pathname. (dirname, entryname) ; 


I GIVEN A DIRECTORY NAME AND AN ENTRY NAME, RETURNS THE PATHNAME 
OF THE ENTRY IN A char (168) 


0 IF THE RESULTING PATHNAME IS >168 CHARACTERS, THE LAST 20 
CHARACTERS OF THE RESULT ARE SET TO "<PATHNAME TOO LONG>" 


#® pathname $component 
J path = pathname $component (dirname, entryname, component_name) ; 


1 GIVEN A DIRECTORY NAME, AN ENTRY NAME, AND OPTIONALLY, AN ARCHIVE 
COMPONENT NAME, CONSTRUCTS A PATHNAME OR AN ARCHIVE COMPONENT 
PATHNAME 


I IF COMPONENT NAME IS NULL AND THE RESULTING PATHNAME IS >168 
CHARACTERS, THE LAST 20 CHARACTERS OF THE PATHNAME ARE SET TO 


ama ome 2am aaAms 


"<PATHHAME TOO LONG>* 


1 IF COMPONENT NAME IS NOT NULL AND THE RESULTING PATHNAME IS 
>194 CHARACTERS, THEN THE LAST 20 CHARACTERS OF THE 
dirname>entryname PORTION OF THE ARCHIVE PATHNAME ARE CHANGED 


TO "<PATHNAME TOO LONG>" AND THE component name REMAINS IN 
THE PATHNAME > 
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MANIPULATING PATHNAMES 


@ pathname $component check 


1 call pathname $component_ check (dirname, entryname, 
component _name, path, code); 


1 SAME AS pathname $component EXCEPT A STATUS CODE INDICATES 
TRUNCATION INSTEAD OF AN INVALID PATHNAME CONTAINING "<PATHNAME 
TOO LONG>" 


@ NOTE: NONE OF THE PREVIOUS SUBROUTINES CHECK TO SEE IF THE ENTRY 
EXISTS 
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ANIPULATING PATHNAMES 


YOU ARE NOW READY FOR WORKSHOP 
#7 
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(End Of Topic) 
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FISC 


Topic Xl MORE MULTICS STORAGE SYSTEM SUBROUTINES Topic XI 
OBJECTIVES: 

Upon completion of this topic, students should be able to: 

1. Move entries from one place in the storase system to another. 


2. Change the lensths and names of entries in the storase 
system. 


3. Add and remove entries to and from the user’s name space. 


Multics : SB Noa FISC 


NAMING AND MOVING DIRECTORY ENTRIES 


# hes $chname file 


1 call hes $chname file (dir_name, entryname, ‘oldname, 
newname, code); 


] ADDS, DELETES, OR CHANGES NAMES OF SEGMENTS, DIRECTORIES, MSFS, 
OR LINKS (SPECIFIED BY NAME) 


f EITHER oldname OR newname-( BUT NOT BOTH) MAY BE null ("") 


0 MODIFY PERMISSION ON CONTAINING DIRECTORY REQUIRED 


@® hes $chname seg 
] call hes $chname_ seg (seg ptr, oldname, newname, code); 
I ADDS, DELETES, OR CHANGES NAMES OF A SEGMENT, GIVEN A POINTER T 
Tt 


] OTHERWISE SIMILAR TO hes $chname file 
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NAMING AND MOVING DIRECTORY ENTRIES 


# hes $fs_move file 


) call hes $fs_move_ file (from_dir, from_entry, at_sw, 
to_dir, to_entry, code); 


1 MOVES CONTENTS OF ONE SEGMENT TO ANOTHER SEGMENT 


] at_sw HAS 2 BITS (fixed bin(2)) 


0 THE APPEND BIT ON FORCES CREATION OF NEW SEGMENT IF IT 
DOESN'T EXIST 


I THE TRUNCATE BIT ON FORCES TRUNCATION OF NEW SEGMENT IF IT 
EXISTS 
I OLD (ZEROED OUT) SEGMENT REMAINS 
I RECORD LENGTH = 0 
I BIT COUNT NOT CHANGED 


1 NEW SEGMENT'S BIT COUNT NOT ADJUSTED 


T ACCESS REQUIRED 
1 READ AND WRITE ON OLD SEGMENT 
I READ, WRITE ON NEW SEGMENT (IF IT EXISTS) 
0 APPEND ON NEW SEGMENT'S CONTAINING DIRECTORY (IF SEG MUST 
BE CREATED) 


0 FOR A SHORT TIME, 2 IMAGES EXIST (POSSIBLE QUOTA PROBLEM) 
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NAMING AND MOVING DIRECTORY ENTRIES 


# hes $fs_move_ seg 


1 call hes $fs_move_seg (from_ptr, to_ptr, trun_sw, ccde); 


I MOVES CONTENTS OF ONE SEGMENT TO ANOTHER, GIVEN POINTERS TO EACH 
I trun_sw HAS ONLY ONE BIT 


| OTHERWISE SIMILAR TO hes $fs_move file 
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® hes $truncate file 


] call hes $truncate file (dir_name, entryname, length, code); 


I TRUNCATES A SEGMENT TO A SPECIFIED LENGTH (IN WORDS), GIVEN ITS 
NAME AND CONTAINING DIRECTORY NAME 


T TRAILING FULL PAGES ARE DISCARDED 
I ZEROES ARE STORED (IN LAST PAGE) BEYOND SPECIFIED LENGTH 
I WRITE. PERMISSION ON TARGET REQUIRED 


I THE BIT COUNT IS NOT SET (USE EITHER hes $set_be OR 
adjust _bit_count_) 


) truncate COMMAND PERFORMS BOTH hes $truncate file AND 
hes $set_be 
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@ hes $set_be 
1 call hes $set_be (dir_name, entryname, bit _count, code); 


I SETS THE BIT COUNT OF A SEGMENT TO A SPECIFIED NUMBER, GIVEN ITS 
NAME AND CONTAINING DIRECTORY 


I ALSO SETS BIT COUNT AUTHOR TO USER ID OF CALLER 
I WRITE PERMISSION ON SEGMENT REQUIRED 
I MODIFY PERMISSION ON DIRECTORY NOT REQUIRED 


| COMMAND INTERFACE: set _bit_count (sbc) 


@® adjust bit _count_ 


1 call adjust_bit_count  (dir_name, entryname, char_sw, 
bit count, code); 


I SETS THE BIT COUNT TO THE LAST NON-ZERO WORD OR BYTE 
I WORKS ON SEGMENTS AND MULTISEGMENT FILES 


I char_sw DETERMINES WHETHER THE BIT COUNT IS ADJUSTED TO THE 
LAST WORD OR CHARACTER 


I COMMAND INTERFACE: adjust_bit_ count (abc) 
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® terminate file_ 
1 call terminate file (seg _ptr, bit count, switches, code); 


I PERFORMS COMMON OPERATIONS OFTEN NECESSARY AFTER A PROGRAM HAS 
FINISHED USING A SEGMENT, SUCH AS 


] SETTING THE BIT COUNT 
I TRUNCATING THE SEGMENT 


I ENSURING THAT BITS IN THE LAST WORD OF THE SEGMENT AFTER THE 
BIT COUNT ARE ZERO 


I TERMINATING A NULL REFERENCE NAME 


I ENSURING THAT ALL MODIFIED PAGES OF THE SEGMENT ARE NO LONGER 
IN MAIN MEMORY 


J USES THE terminate file switches STRUCTURE 
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AFFECTING THE LENGTH OF A FILE 


/* BEGIN INCLUDE FILE wild eermsaare. file.incl.pl1 */ 
/* format: style2,*inddels,idind32 ¥/ 


declare 1 terminate file switches 


declare 
declare 
declare 
declare 
declare 
declare 


declare 


2 truncate 

2 set_be 

2 terminate 

2 force write 
2 delete 


TERM FILE TRUNC 

~statie options 
TERM FILE BC 

static options 
TERM_FILE TRUNC_BC 

“static options 
TERM_FILE TERM 

static options 
TERM FILE TRUNC_BC TERM 

“static options 
TERM FILE FORCE WRITE 

static options 
TERM FILE DELETE 

Static options 


base 


bit 
bit 
bit 
bit 
bit 


bit 
(constant) 
bit 
(constant) 
bit 
(constant) 
bit 
(constant) 
bit 
(constant) 
bit 
( constant) 
bit 
(constant) 


? 

1) unaligned, 
1) unaligned, 
1) unaligned, 
1) unaligned, 
1) unaligned; 


(1) internal 
initial ("1"b); 
(2) internal 
initial ("01"b); 
(2) internal 
initial ("11"b); 
(3) internal 


initial ("001"b); 


(3) internal 


initial €"117"b); 


(4) internal 


initial ("0001"b) ; 


(5) internal 


initial ("00001"b); 


/* END INCLUDE FILE ... terminate file.incl.pl1 */ 


1 terminate file 


SHOULD NEVER BE CALLED FROM A CLEANUP HANDLER 


WITH THE truncate OR set_be SWITCHES ON (seg_ptr MAY CONTAIN AN 
INVALID SEGMENT NUMBER) 


3 


force write SHOULD BE USED ONLY WHEN DATA INTEGRITY IS ABSOLUTELY 


ESSENTIAL AS IT MAY INTRODUCE A SUBSTANTIAL REAL TIME DELAY IN 
EXECUTION 
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@ DEFINITION OF TERMS 


I ADDRESS SPACE IS 


I THE PER=-PROCESS COLLECTION OF SEGMENTS THAT CAN BE DIRECTLY 
REFERENCED VIA HARDWARE 


I EXPANDING AND CONTRACTING DURING A PROCESS' LIFE 
I A COLLECTION OF "KNOWN" SEGMENTS 
I REFLECTED IN THE DSEG (AND KST) 


) MANAGED 
T AUTOMATICALLY BY THE DYNAMIC LINKER 
I IMPLICITLY, BY A CALL TO SOME SYSTEM COMMAND 
EXAMPLE: print my _dir>my_seg 


0 EXPLICITLY, BY USER CALLS TO SYSTEM COMMANDS OR SUBROUTINES 
THAT MANAGE THE ADDRESS SPACE 
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1 NAME SPACE IS 


I THE PER=PROCESS COLLECTION OF "REFERENCE" NAMES (OPTIONALLY) 
ASSOCIATED WITH EACH "KNOWN" SEGMENT 


I EXPANDING AND (RARELY) CONTRACTING DURING A PROCESS' LIFE 
] REFLECTED IN THE REFERENCE NAME TABLE (RNT) 
J AN IMPORTANT PART OF SEARCH RULES (INITIATED SEGMENTS LIST) 


0 MANAGED 
] AUTOMATICALLY BY THE DYNAMIC LINKER 


I EXPLICITLY, BY USER CALLS TO SYSTEM COMMANDS OR SUBROUTINES 
THAT MANAGE THE NAME SPACE 


I MAKING-KNOWN INVOLVES 


] DEVELOPING A POINTER TO A SPECIFIED MEGMENT (ASSIGNING A SEGMENT 
NUMBER ) 


1 ADDING AN ENTRY TO THE KST AND DSEG 


] INITIATING (A REFERENCE NAME) INVOLVES 
I EXPANDING THE PROCESS' NAME SPACE 


I ADDING AN ENTRY TO THE RNT 
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0 TERMINATING (A REFERENCE NAME) INVOLVES 
[ CONTRACTING THE PROCESS' NAME SPACE 


I REMOVING AN ENTRY FROM THE RNT 


I MAKING-UNKNOWN INVOLVES 
I MAKING A. PREVIOUSLY VALID SEGMENT NUMBER INVALID 


[ FREEING UP THAT SEGMENT NUMBER FOR FUTURE REASSIGNMENT 
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® NOTES 


I INITIATING A REFERENCE NAME MAY TRIGGER THE MAKING-KNOWN OF A 
SEGMENT 


I TERMINATING A REFERENCE NAME MAY TRIGGER THE MAKING-UNKNOWN OF A 
SEGMENT 


I AN UNKNOWN SEGMENT CAN NOT HAVE A REFERENCE NAME 
I A KNOWN SEGMENT MAY HAVE A NULL REFERENCE NAME . 


T PRESENCE IN THE RNT IMPLIES PRESENCE IN THE DSEG (AND KST) 
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@ TERMINATING SEGMENTS USING term_ 


J term _$term_ 


0 call term_$term_ (dir_path, entryname, code); 

I REMOVES ALL REFERENCE NAMES FROM RNT 

I REMOVES SEGMENT FROM CALLER'S ADDRESS SPACE 
I REMOVES SEGMENT FROM COMBINED LINKAGE SECTION 
I 


UNSNAPS LNKS IN COMBINED LINKAGE QECTION THAT CONTAIN 
REFERENCES TO THE SEGMENT 


| 


USER SUPPLIES dir_path AND entryname 


) COMMAND INTERFACE: terminate (tm) 


H} term_$seg_ ptr 


1 call term_$seg_ptr (seg ptr, code); 
I LIKE term_$term_, BUT ACCEPTS A PTR TO SEGMENT 


[ COMMAND INTERFACE: terminate_segno (tms) 


1 term_$refname 


§ call term $refname (ref name, code); 
I] LIKE term_$term_, BUT ACCEPTS A REFERENCE NAME 
J COMMAND INTERFACE: terminate refname (tmr) 
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MANIPULATING THE ADDRESS AND NAME SPACES 


1 term_$single refname 


1 call term_$single refname (ref_name, code); 
I REMOVES A SINGLE REFERENCE NAME FROM RNT 


I] BEHAVES LIKE term $refname (I.E. SEGMENT IS NOT MADE UNKNOWN) 
IFF REFNAME SPECIFIED WAS SEGMENT'S ONLY INITIATED REFNAME 


I COMMAND INTERFACE: terminate single _refname (tmsr) 


) term_$unsnap 
J call term_$unsnap (seg ptr, code); 


I] UNSNAPS LINKS ONLY 
— DOESN'T TERMINATE REFERENCE NAMES OR MAKE SEGMENT UNKNOWN 


T NO COMMAND LEVEL INTERFACE 
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® initiate file 
1 MAKES A SEGMENT KNOWN WITH A NULL REFERENCE NAME 


I (PREVIOUSLY DISCUSSED IN TOPIC 5) 


@® terminate file_ 
0 TERMINATES A NULL REFERENCE NAME 


J (PREVIOUSLY DISCUSSED IN THIS TOPIC) 


Not To Be Reproduced 11-14 F15C 


EXAMINING THE ADDRESS AND NAME SPACES 


® hes $fs_ get _path_name 


1 call hes | $fs_get_ path_ name (seg ptr, dir_name, ldn, 
entryname, code); 


I GIVEN A POINTER TO A SEGMENT, RETURNS A PATHNAME FOR THE SEGMENT, 
WITH THE DIRECTORY AND ENTRYNAME PORTIONS SEPARATED (THE ENTRYNAME 
RETURNED IS THE PRIMARY NAME ON THE ENTRY) 


® nes $fs_get_ref_name 
J call hes $fs_get_ref_ name (seg ptr, count, ref name, code); 


] RETURNS A SPECIFIED (I.E., FIRST, SECOND, ETC.) REFERENCE NAME 
OF A SPECIFIED SEGMENT, GIVEN A POINTER TO THE SEGMENT 


@ hes $fs_get_seg_ ptr 
J call hes $fs_get_seg_ptr (ref_name, seg ptr, code); 


I GIVEN A REFERENCE NAME OF A SEGMENT, RETURNS A POINTER TO THE BASE 
HAT SEGMEN 
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PATHNAME, POINTER, REFERENCE NAME CONVERSION 


REFERENCE 
NAME 
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PATHNAME, POINTER, REFERENCE NAME CONVERSION 


YOU ARE NOW READY FOR WORKSHOP 
#8 
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(End Of Topic) 
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Commands and Active Functions 
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Toric XII COMMANDS AND ACTIVE FUNCTIONS Topic XII 
OBJECTIVES: 
Upon completion of this toric, students should be able to: 


1. Describe the differences between a command and an active 
function. 


2. Write a command which takes a varying number of arsuments, 
validates them, and performs some task. 


3. Write an active function which accepts a varyins number of 
arguments; validates them, and returns an appropriate value. 


4. Use Multics subroutines to report errors encountered during 
execution of a command or active function. 


5. Use Multics subroutines to acauirse and release temporary 
workins storage. 


& Use the Multics clock and timer functions. 
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COMMANDS 
_ CHARACTERISTICS OF A COMMAND 


@ A COMMAND PROCEDURE IS AN OBJECT PROGRAM WHICH IS DESIGNED TO BE 
INVOKED FROM COMMAND LEVEL 


@® A COMMAND PROCEDURE MUST OPERATE WITHIN STRICT OPERATIONAL LIMITATIONS, 
AND IT IS THESE LIMITATIONS THAT MAKE IT DIFFERENT FROM OTHER PROCEDURES 


@® MANY SYSTEM SUBROUTINES CALLED BY COMMAND PROCEDURES RETURN PL/I 
POINTER VALUES, THUS FORCING THE AUTHOR TO CODE THE COMMAND PROCEDURE 
IN PL/I 
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COMMANDS 


DIFFERENCES BETWEEN A COMMAND AND A PROGRAM 


<— ee te GS Geet 


@ THE DIFFERENCES WHICH EXIST BETWEEN A COMMAND PROGRAM AND A REGULAR 
PROGRAM ARE DEFINED BY THE THREE RESTRICTIONS BELOW: 


BECAUSE THE COMMAND IS CALLED BY THE MULTICS COMMAND PROCESSOR 
(OR A USER-DESIGNED COMMAND PROCESSOR) 


J INPUT ARGUMENTS ARE LIMITED TO 'nonvarying unaligned character 
string s' 


1 HENCE, A COMMAND IS RESPONSIBLE FOR CONVERTING THESE STRINGS 
TO WHATEVER DATA TYPES ARE REQUIRED 


A COMMAND CAN RECEIVE ONLY INPUT ARGUMENTS 


I THE COMMAND CANNOT CHANGE THE VALUE OF ANY OF THESE INPUT 
ARGUMENTS 


THE COMMAND MUST BE PREPARED TO HANDLE AN ARBITRARY NUMBER OF 
ARGUMENTS - THERE ARE NO PARAMETER DECLARATIONS ALLOWED 


| IF THE COMMAND IS PASSED TOO MANY ARGUMENTS, IT MUST COMPLAIN 
AND ABORT (CONSIDER HOW THE SYSTEM HANDLES "pwd a") 


OTHER RULES FOR MULTICS SYSTEM COMMANDS 


I USE com_err_ TO REPORT ERRORS 
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COMMANDS 
REPORTING ERRORS 


@® WHEN A COMMAND PROCEDURE DETECTS SOME ERROR, IT IS RESPONSIBLE FOR 
REPORTING IT TO THE USER IN A STANDARD FASHION: 


] com_err_ 


1 THE PRINCIPAL SUBROUTINE USED BY COMMANDS FOR PRINTING ERROR 
MESSAGES 


[I IT IS GENERALLY CALLED WITH A NONZERO STATUS CODE TO REPORT 
SOMETHING UNUSUAL 


] IT MAY ALSO BE CALLED WITH A CODE OF 0 TO REPORT AN ERROR NOT 
ASSOCIATED WITH A STATUS CODE 
I declare com_err_ entry options( variable); 


call com_err_ (code, caller, control string, argi, ..., 
argN); 


] control string IS AN OPTIONAL ioa_ SUBROUTINE CONTROL STRING 
(INPUT) 


1 argi eo, argN ARE ioa SUBROUTINE ARGUMENTS TO BE 
SUBSTITUTED INTO THE control_string (INPUT) 
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COMMANDS 


THE ERROR MESSAGE PREPARED BY com_err_ HAS THE FORM: 
J caller: system_message user_message 


0 FOR SYSTEM COMMANDS caller IS THE NAME OF THE PROGRAM 
DETECTING THE ERROR 


I EXAMPLE: (IF code = error_table $wrong_no_ of args AND nargs 
= 5) 7 


0 PL/I STATEMENT: 


call com_err_ (code, "sample command", 
"“/You furnished “d args.", nargs); 


I RESULT: 


Sample command: Wrong number of arguments supplied. 
You furnished 5 args. 


ti 


IF CODE = 0 ONLY A user_message IS PRINTED 
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COMMANDS 
COMMAND 1/0 


@ IN WRITING COMMAND PROCEDURES NO LANGUAGE LEVEL I/O STATEMENTS ARE 
EVER USED 


@® STANDARD INPUT/OUTPUT IS DONE USING THE FOLLOWING SUBROUTINES: 


I ioa_ 


) USED FOR FORMATTING A CHARACTER STRING 


1 iox_ 


0 THE SUBROUTINE-LEVEL INTERFACE FO THE MULTICS I/0 SYSTEM 


{| command query_ 


[ THE STANDARD SYSTEM PROCEDURE INVOKED TO ASK THE USER A QUESTION 
AND OBTAIN AN ANSWER 


"] IT PRINTS THE QUESTION ON THE USER'S TERMINAL, AND THEN READS 
THE 'user_imput' SWITCH TO OBTAIN THE ANSWER 
I declare command query _ entry options( variable) ; 


call command query (ptr, answer, caller, control string, 
arg1, ..., argN); 


T ptr POINTS TO THE query_info STRUCTURE DESCRIBED ON THE 
FOLLOWING PAGE (INPUT) 
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COMMANDS 
COMMAND I/0 


/* BEGIN INCLUDE FILE query _info.inel.pl1 TAC June 1, 1973 #*/ 
/* Renamed to query info.incl.pl1 
and cp escape control added, 08/10/78 WOS #/ 
/* version number changed to 4, 08/10/78 WOS #/ 
/* Version 5 adds explanation_ (ptr len) 05/08/81 S. Herbst *#/ 
/* Version 6 adds literal_sw, prompt_after_explanation switch 
12715/82 S. Herbst */ 


del 1 query _info aligned, 
/* ‘argument structure for command query _ call */ 
2 version fixed bin, 
/* version of this structure < must be set, see below */ 
2 switches aligned, 
/* various bit switch values */ 
3 yes or_no_sw bit (1) unaligned init ("0"b), 
/¥* not a yes-or-no question, by default #/ 
3 suppress name _sw bit (1) unaligned init ("0"b), 
/* do not suppress command name */ 
3 cp_escape control bit (2) unaligned init ("00"b), 
7* obey static default value */ 
/* "01" => invalid, "10" => don't allow, "11" -> allow *#/ 
suppress spacing bit "1) unaligned init ("9 "b) , 
/* whether to print extra spacing */ 
literal_sw bit (1) unaligned init ("0"b), 
/* ON => do not strip leading/trailing "white Space */ 
prompt after_explanation bit (1) unaligned init ("0"b), 
/* ON => repeat question after explanation */ 
3 padding bit (29) unaligned init (""b), 
/* pads it out to t word */ 
2 status code fixed bin (35) init (0), 
/* query not prompted by any error, ay default */ 
2 query code fixed bin (35) init (0), 
/* Currently has no meaning */ 


Ww Ww Ww 


/* Limit of data defined for version 2 */ 


2 question_iocbp ptr init (nuli ()), 
/* IO switch to write question */ 
2 answer_iocbp ptr init (null ()), 
/* I0 switch to read answer +} 
2 repeat_time fixed bin (71) init (0), 
/* repeat question every N seconds if no answer */ 
/* minimum of 30 seconds required for repeat */ 


/* otherwise, no repeat will occur */ 
/* Limit of data defined for version 4 #/ 
2 explanation_ptr ptr init (null ()), 
/* explanation of question to be printed if */ 
2 explanation_len fixed bin (21) init (0); 
/* user answers "?" (disabled if ptr= null or len=0) */ 
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COMMANDS 


COMMAND I/0 


del query _info_ version_3 fixed bin int static 
options (constant) init (3); 
del query info _version_4 fixed bin int static 
options (constant) init (4); 
del query _info_version_5 fixed bin int static 
options (constant) init (5); 
del query _info_version_6 fixed bin int static 
options (constant) init (6); 
/* the current version number *#/ 


/* END INCLUDE FILE query_info.inel.pl1 */ 
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COMMANDS 
OTHER SUBROUTINES USED IN WRITING COMMANDS 


0 USED TO MANIPULATE THE COMMAND ENVIRONMENT IN FUNCTIONS LIKE: 
I SETTING THE READY MESSAGE 
I CALLING THE COMMAND PROCESSOR 
I CHANGING THE COMMAND PROCESSOR 


I EXAMINING STACK FRAMES 
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COMMANDS 
OTHER SUBROUTINES USED IN WRITING COMMANDS 


® THE FOLLOWING ENTRIES ARE USED TO OBTAIN THE ARGUMENTS PASSED TO 
THE COMMAND 


I cu_$arg_count 
1 call cu_$arg_count (arg count, code); © 


IT USED TO DETERMINE THE NUMBER OF ARGUMENTS SUPPLIED WHEN THE 
PROCEDURE WAS CALLED 


I cu_$arg_ptr 
1 call cu_$arg_ ptr (arg_no, arg ptr, arg_len, code); 


I RETURNS A POINTER TO AND THE LENGTH OF ONE OF THE ARGUMENTS 
] arg_no IS AN INTEGER SPECIFYING THE NUMBER OF THE DESIRED 
ARGUMENT (INPUT) 
f NOTE THAT A BASED VARIABLE IS NORMALLY USED FOR INPUT ARGUMENTS 
AND IS DECLARED AS FOLLOWS: 


I declare argument char(arg_len) based(arg_ptr); 
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COMMANDS 
OTHER SUBROUTINES USED IN WRITING COMMANDS 


@® EXAMPLES 


Sample command: proc; 


del cu_$arg_count entry(fixed bin, fixed bin(35)); - 

del nargs fixed bin; 

del error table _ $wrong no_of_args fixed bin(35) external; 
del com_err_ entry options( variable); 

del code fixed bin(35); 


call cu_$arg_ count (nargs, code); 
if nargs “= 0 
then do; 
call com_err_(error_ table $wrong_no of args, 
"sample_ command") ;— 
return; 
end /* then do */; 


sample _command2: proc; 


del cu_$arg_ ptr entry (fixed bin ,ptr, fixed bin(21),fixed bin(35)); 
del argument char(arg_len) based(arg_ptr); 
del arg_len fixed bin(21); 
del arg ptr ptr; 
del code fixed bin(35); 
del (com_err_, ioa_) entry options( variable); 


sali: eu 1 $arg_ ptr (1, arg ptr, arg_len, code); 


if code *= 0 
then do; 


call com_err_ (code, "sampie_command2") ; 
return; 
end /* then do #/; 
call ioa_ ("First argument is “a",argument) ; 
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COMMANDS 
OTHER SUBROUTINES USED IN WRITING COMMANDS 


@® THE FOLLOWING SUBROUTINES ARE USED FOR ARGUMENT CONVERSION: 


] expand_pathname_ 
) call expand_pathname (pathname, dirname, entryname, code); 
1 PREVIOUSLY DISCUSSED IN TOPICS 5 AND 10 


I NOTE THAT SOME CRITICAL MULTICS SUBROUTINES REQUIRE A PATHNAME 
ARGUMENT SPECIFIED IN TWO PORTIONS, THE DIRECTORY PATHNAME 
AND THE ENTRYNAME, AND THIS IS ONE OF THE MAIN REASONS 
expand pathname. IS AVAILABLE 


T cv_ptr_ 
0 ptr_value = cv_ptr_ (vptr, code); 


1 THIS FUNCTION CONVERTS A VIRTUAL POINTER TO A POINTER VALUE 
(A VIRTUAL POINTER IS A CHARACTER=STRING REPRESENTATION OF A 
POINTER VALUE, SUCH AS "foogbar" OR ">udd>PROJ>PERS>seg | 1200") 
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COMMANDS 
‘OTHER SUBROUTINES USED IN WRITING COMMANDS 


] OTHER CONVERSION SUBROUTINES AND FUNCTIONS 


] ev_bin_ 
1 ecv_bin.$dec 


0 ev_bin_$oct 
1 ev_dec_, cv_dec _check_ 
1 ev_oct_, cv_oct_ check_ 


1 cv_hex_, cv_hex_check_ 


2 ecv_float_ 
1 ev float double 


1 cv_ptr_$terminate 
) ev_entry_ 

1 cv_mode_ 

1 cv_dir_mode_ 

1 cv_userid_ 


) cv_error_ 


J cv_error $name 
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COMMANDS 
OTHER SUBROUTINES USED IN WRITING COMMANDS 


This Page Intentionally left Blank 
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COMMANDS 
AN EXAMPLE OF A COMMAND 


how_long: proc; 


del cu_$arg_count entry (fixed bin, fixed bin (35)); 

del cu _$arg_ptr entry (fixed bin, ptr, fixed bin(21), fixed bin (35)); 

del expand_pathname_ entry (char (*), char (*), char (*), fixed bin (35)); 

del hes $status_minf entry (char(*), char(*), fixed bin(1), fixed bin(2), 
fixed bin(24), fixed bin(35)); 


del long bit (1) init ("0"b); 
del arg char (argl) based (argp); 
del (i, nargs) fixed bin; 
del argl fixed bin(21); 
del argp ptr; 
del type fixed bin (2); 
del code | fixed bin (35); 
del dir char (168); 
del entry char (32); 
del (com_err_, 
ioa_) entry options (variable); 
del ME char (8) static init Chow, long") options (constant); 
del be fixed bin (24); 
del null builtin; 


del error_table $wrong_no_of_args fixed bin(35) external; 
—/* check number of args */ 


call cu_$arg_count (nargs, code); 
if (margs < 1) | (nargs > 2) 
then do; 
call com_err_ (error_table $wrong_no_of args, ME); 
return; 
end /*® then do */; 


/* evaluate args */ 


do i,= 1 to nargs; 
eall ecu | $arg_ptr (i, argp, argl, code); 


if is 1 
then do; 
call expand_pathname (arg, dir, entry, code); 
if code “= 0 
then do; 
: con err (cade, ME); 
end /* ae do *#/; 
call hes $status_minf (dir, entry, 1, type, be, code); 
if code “= 0 
then do; 
call com_err_ (code, ME); 
return; 
end /* then do #/; 
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COMMANDS 
AN EXAMPLE OF A COMMAND 


be = be/36; 
end /* then do *#/; 
else do; 
/* second arg must be -long or -lg */ 
if (arg = "-long") | (arg = "=-1g") 
then long = "1"b; 
else do; 
call com_err_ (0, ME, "Control arg must be -long or -lg" 
return; 
end /* else do */; 
end /* else do #/; 
end /* do i */; 


call ioa_("*{Number of words for “a>“a is *;“2s*]*i", long, dir, entry, be) 


end /* how_long */; 


r 14:03 0.197 18 


! how long 
how_long: Wrong number of arguments supplied. 
r 14:04 0.183 11 


! how_long how_long 


OO0U 


r 14:04 0.105 0 


! how_long how_long.pli -lg 
Number of words for >user_dir_dir>MED>Jackson>15¢e>how_long.pl1 is 544 
r 14:04 0.088 0 


! how long how long.pli -short. 


how long: Control arg must be -long or <lg 
r 14:04 0.143 1 
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ACTIVE FUNCTIONS 


@ AN ACTIVE FUNCTION RETURNS A CHAR VARYING VALUE TO THE COMMAND 
PROCESSOR FOR SUBSTITUTION INTO THE COMMAND LINE 


] IT IS CALLED BY THE COMMAND PROCESSOR FOR THE PURPOSE OF RETURNING 
A VALUE TO THE COMMAND PROCESSOR 


I THE COMMAND PROCESSOR MUST PREPARE A LOCATION FOR THE RETURNED 
VALUE 


1 THE ACTIVE FUNCTION MUST KNOW THIS LOCATION IN ORDER TO RETURN A 
VALUE 


@® AN ACTIVE FUNCTION DIFFERS FROM A STANDARD PROCEDURE IN THE THREE 
WAYS SPECIFIED FOR COMMANDS (TAKES ONLY CHARACTER-STRING ARGUMENTS, 
HANDLES ONLY INPUT ARGUMENTS, TAKES A VARYING NUMBER OF ARGUMENTS) 
AND HAS ONE ADDITIONAL DIFFERENCE: 


1 AN ACTIVE FUNCTION MUST RETURN A VARYING CHARACTER-STRING ARGUMENT 
TO THE COMMAND PROCESSOR IN. A LOCATION SPECIFIED BY THE COMMAND 
PROCESSOR 


@® A COMMAND PROCEDURE CAN BE WRITTEN TO IMPLEMENT EITHER A COMMAND OR 
AN ACTIVE FUNCTION. 


@® SUCH A PROCEDURE'S EXECUTION DEPENDS ON THE MANNER IN WHICH IT WAS 
INVOKED 
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ACTIVE FUNCTIONS 
SUBROUTINES USED FOR WRITING ACTIVE FUNCTIONS 


@® THE SUBROUTINES USED FOR WRITING AN ACTIVE FUNCTION MUST BE ABLE TO 
DETERMINE TWO VERY IMPORTANT THINGS: 


] THE LOCATION INTO WHICH IT SHOULD PLACE ITS RETURN VALUE 


| WHETHER OR NOT IT WAS INVOKED AS A ACTIVE FUNCTION 


@ cu_$af_arg_ count 
J call cu_$af_arg_count (nargs, code); 
I RETURNS THE NUMBER OF INPUT ARGUMENTS 


1 IF THE CALLER WAS NOT INVOKED AS AN ACTIVE FUNCTION, A NON-ZERO 
STATUS CODE IS RETURNED (error _table $not_act_ fen) 


@® cu $af_arg_ ptr 
1 call cu_$af_arg ptr (arg_no, arg ptr, arg_len, code); 


] OPERATES LIKE cu_$arg_ptr EXCEPT THAT IT RETURNS A NULL arg_ptr 
IF IT WAS NOT CALLED AS AN ACTIVE FUNCTION 


1 USUALLY USED IN WRITING PROGRAMS THAT CAN ONLY BE CALLED AS 
ACTIVE FUNCTIONS 


Not To Be Reproduced 12-17 a F15C 


ACTIVE FUNCTIONS 
SUBROUTINES USED FOR WRITING ACTIVE FUNCTIONS 


_ cu_$af_return_arg 


1 call cu_$af_ return arg (nargs, rtn_string ptr, max_length, 
code); 


] PERFORMS THE JOB OF cugaf_arg_ count AND 


0 MAKES THE ACTIVE FUNCTION'S RETURN ARGUMENT AVAILABLE 


Pari y ptr IS A POINTER TO THE VARYING STRING RETURN ARGUMENT 
OF FUNCTION (OUTPUT) 


HT (max Ea eee THE MAXIMUM LENGTH OF THE VARYING STRING POINTED 
string ptr (OUTPUT) 


0 IF THE CALLER WAS NOT INVOKED AS AN ACTIVE FUNCTION, A NON-ZERO 
STATUS CODE IS RETURNED (error_table $not_act fen) 


) NOTE THAT THE ACTIVE FUNCTION DECLARES ITS RETURN ARGUMENT AS 
FOLLOWS: 


declare return_string char (max_length) varying 
based (rtn_string_ptr); 
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ACTIVE FUNCTIONS 
REPORTING ERRORS 


@ AN ACTIVE FUNCTION USES A DIFFERENT SUBROUTINE FOR REPORTING ERRORS 
TO THE USER: 


] active _fne_err_ 
2 CALLED BY AN ACTIVE FUNCTION WHEN IT DETECTS AN ERROR 


] FORMATS AN ERROR MESSAGE MUCH LIKE com_err_ AND THEN SIGNALS 
THE ‘active function_error' CONDITION 


I USAGE 
I declare active _fne_err_ entry options(variable) ; 


J call active fne_err_ (code, caller, control string, argi, 
neces arg N)s 


| THE USAGE IS SIMILAR IN ALL RESPECTS TO com_err_ 
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-CTIVE FUNCTIONS 
AN ACTIVE FUNCTION EXAMPLE 


me: proc; 


del cu_$af_return_arg entry (fixed bin, ptr, fixed bin(21), fixed bin (35)); 


del nargs fixed bin; 
del return_arg char (rslength) varying based (rsptr); 
del rslength fixed bin (21); 
del rsptr ptr; 
del code fixed bin (35); 
del user info entry (char (); char (*#), char (*)); 
del (active_fne_err_, 
com_err_) entry options (variable); 
del error_ table , $wrong_no of _args fixed bin (35) external; 
del person_id char (22); 
del project_id char (9); 
del aect char (32); 


/* DETERMINE IF INVOKED AS ACTIVE FUNCTION */ 


eall cu_$af_return_arg (nargs, rsptr, rslength, code); 
if code “= Q 
then do; 
call com_err_ (code, "me"); 
return; 
end /* then do */; 


if nargs “= 0 
then do; 
call active fne_err_ (error table $wrong_no_of args,"me"); 
return; 
end /* then do */; 
/* 30 FAR, SO GOOD = GET PERSON ID */ 


call user_info_ (person_id, project_id, acct); 
return _arg = person_ ids 


end /* me */; 
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ACTIVE FUNCTIONS 
AN ACTIVE FUNCTION EXAMPLE 


r 15:19 0.143 0 

! me 
me: This active function cannot be invoked as a command. 
r 15:19 0.197 5 


! who [me] 
Jackson.MED 


r 15:20 0.524 5 


! who [me Jackson] 
me: Wrong number of arguments supplied. 


Error: Bad call to active function me 
r 15:20 0.206 9 level 2 
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COMMANDS AND ACTIVE FUNCTIONS 


@ THE SUBROUTINES DISCUSSED PREVIOUSLY ARE USED IN WRITING PROCEDURES 
THAT MAY BE CALLED AS BOTH COMMANDS AND ACTIVE FUNCTIONS 


@® THE FOLLOWING SUMMARIZES THE IDIOSYNCRASIES TO BE CONSIDERED IN 
CHOOSING APPROPRIATE SUBROUTINES 


ACT. 
cu_ ENTRY COMMAND FUNC. COMMENTS 
arg count IF INVOKED AS AN ACTIVE FUNCTION 
COUNT INCLUDES RETURN ARGUMENT 
arg ptr 
af_arg_ count COUNT EQUALS INPUT ARGUMENTS ONLY 
af_arg ptr NULL arg ptr IF INVOKED AS A COMMAND 
af_return_arg x X COUNT EQUALS INPUT ARGUMENTS ONLY 
NULL rtn_ptr IF INVOKED AS A COMMAND 
@® IT IS ALWAYS POSSIBLE TO WRITE ANY COMMAND OR ACTIVE FUNCTION USING 


ONLY THE TWO ENTRY POINTS, cu_$af_return_arg AND cu_$arg_ptr 
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COMMANDS AND ACTIVE FUNCTIONS 
AN EXAMPLE OF A COMMAND/ACTIVE FUNCTION 


how_long both: proc; 


del expand pathname entry (char (*), char (*), char (*), fixed bin (35)); 

del cu_$arg_ptr entry (fixed bin, ptr, fixed bin(21), fixed bin(35)); 

del cu | $af_ return_ arg entry(fixed bin, ptr, fixed bin(21), fixed bin (35)} 

del active fne_err_ entry options (variable); 

del nes $status_minf entry (char(*), char(*), fixed bin(1), fixed bin(2), 
fixed bin(24), fixed "bin(35)); 

del long bit (1) init ("0"b); 

del arg char (argl) based (argp); 

dcl complain entry variable options (variable); 

del af bit (1) init ("0"b); 

del return_string char (rslength) var based (rsptr); 

del rslength fixed bin (21); 

del rsptr ptr; 

del (i, nargs) fixed bin; 

del argl fixed bin (21); 

del argp ptr; 

del type fixed bin (2); 

del code fixed bin (35); 

del dir char (168); 

del entry char (32); - 

del (com_err_, ioa_) entry options (variable); 

del ME Ghar (13) Static init ("how_long_ both") options (constant); 

del be fixed bin (24); 

del error_table $wrong_no_of_args fixed bin(35) external; 


/* check number of args *#/ 
call cu_$af_return_arg (nargs, rsptr, rslength, code); 
/* command or active function invocation??? */ 


if code = 0 
then do; 
at 47 "b; 
complain = active _fne_err ; 
end /* then do #/; 
else complain = com_err_; 


if (nargs < 1) {| (nargs > 2) 
then do; 
call complain (error_table $wrong_no_of args, ME); 
return; 
end /* then do */; 


/* evaluate args *#/ 


do i= 1 to nargs; 
call cu_$arg_ ptr (i, argp, argl, code); 
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COMMANDS AND ACTIVE FUNCTIONS 
AN EXAMPLE OF A COMMAND/ACTIVE FUNCTION 


/* relative pathname argument */ 


if it. 4 
then do; 


call expand_pathname (arg, dir, entry, code); 
if code “= 0 
then do; 
call complain (code, ME); 
return; 
end /* then do *#/; 


call hes $status_minf (dir, entry, 1, type, be, code); 
if code “= 0 
then do; 
call complain (code, ME); 
return; 
end /* the do #/; 
be = be/36; 


end /* then do #/; 


else do; 


/* second arg must be -long or =lg #/ 


if (arg = "=long") | (arg = "=1g") 
then long = "1"b; 
else do; 
call complain (0, ME, "Control arg must be -long or -lg"); 
return; 
end /* else do #/; 


end /* else do #/; 


end /* do i *#/; 


if af 
then do; 


return string = be; 


5 


return; 
end /* then do #*/; 


call ioa_("*({Number of words for “a>“a is ~;*2s*]*i", long, dir, entry, be); 


end /* how_long_ both */; 
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COMMANDS AND ACTIVE FUNCTIONS 
AN EXAMPLE OF A COMMAND/ACTIVE FUNCTION 


r 15:59 0.284 7 


! how_long_ both 
how j_ long _ both: Wrong number of arguments supplied. 
r 15:59 0.152 11 


! how_long both foo -lg 
how long both: Entry not found. 
r 16:00 0.118 0 


! how_long both how_long_ both 
776, 
r 16:00 0.076 0 


! how_long both how long both -long 
Number of words for >user_ dir_dir>MED>Jackson>fi5¢e>how_long both is 776 
r 16:01 0.098 0 


! octal [how_long_ both how_long_ both] 
1410 
r 16:01 0.196 6 


! octal [how_long_ both] 
how_long_ both: Wrong number of arguments supplied. 
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OTHER USEFUL SUBROUTINES 


@ user _info_ 


] RETURNS INFORMATION CONCERNING A USER'S LOGIN SESSION (ALL ARGUMENTS 
ARE OUTPUT ARGUMENTS) 


0 call user_info_ (person_id, project id, acct); 


I OTHER ENTRY POINTS: 
I call user_info_ $absentee_ queue (queue); 
] call user_info_$absentee _request_id (request_id); 
J call user_info_ $absin (path); 
2 call user_info $absout (path); 
J] call user_info $attributes (attr); 
1 call user_info $homedir (hdir); 


] call user_info $limits (mlim, clim, cdate, crf, shlim, msp, 
esp, shsp); 


I call user_info_$load_ctl_info (group, stby, preempt time, 
weight); 


] call user_info_ $login_arg_count (count, max_length, 
total length); 


] call user_info_ $login_arg_ ptr (arg_no, arg ptr, arg_len, 
code); 
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OTHER USEFUL SUBROUTINES 


J call user_info $login_data (person_id, project_id, acct, 
anon, stby, weight, time _ login, 
Login_word) ; 


] call user_info $logout_ data (logout_ channel, logout_pid); 
] call user_info_$outer_module (om); 

I call ser dia?o. process: Ayre (process type); 

I call user_info_$responder (resp); 

J] call user_info_ $rs_name (rs_name); 

IT call user_info_$rs_number (rs_ number) ; 

I] call user_info $service type (type); 


T call user_info $terminal_ data (id_code, type, channel, 
line -_ type, charge_ type); 


] call user_info_ $usage data (nproc, old_cpu, time login, 
time ) create, old _mem, 
old_ To )_ eps) ; 


1 call usér_info $whoami (person_id, project_id, acct); 
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@® value_ 


I 


I 


I 


OTHER USEFUL SUBROUTINES 


READS AND MAINTAINS VALUE SEGMENTS CONTAINING NAME-VALUE PAIRS 
ACROSS PROCESS BOUNDARIES 


CREATING A VALUE SEGMENT 


I CREATE A SEGMENT WITH A SUFFIX OF .value 


call 
DEFAULT 
' ] eall 
—[ call 


value_$init_seg (seg_ptr, seg type, remote area ptr, 
seg size, code); 


VALUE SEGMENT IS [home _dir]>{user_name].value 
value_$set_path (path, create sw, code); 


value_$get_path (path, code); 


CREATING AND MAINTAINING NAME-VALUE PAIRS 


— call 
I call 
1 call 
I call 
I eall 
1 eall 


value $set (seg ptr, switches, name, new value, 
old_value, code); 


value _$test_and_ set (seg ptr, switches, name, new value, 
old_ value, code); 


value $get (seg ptr, switches, name, value_arg, code); 


fake 


Val ue List_ 1 


value $list (set_ptr, Switches,match_info_ptr, area ptr, 
nfo r 


es, 
ode im a Ne 
ee gee eg 
value _$defined (seg ptr, switches, name, code); 


value_$delete (seg _ptr, switches, name, code); 
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OTHER USEFUL SUBROUTINES 


| YOU ARE NOW READY FOR WORKSHOP 
{| = 
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WORKSHOP ONE 


Controlled Variables and 'isub' Defining 


_ Write a procedure called ‘allocate array.pli} that will ask the 


user for the size of one dimensional fixed bin (17) arrays he/she 
wishes to allocate. For example, if the user provides the number 


7, your program is to allocate an array with fixed bin (17) 


elements. 
Bdestictsss aki 


The program should loop, repeatedly asking for the size 
next array, allocating that array and then tga te att 7 ng ahs spenents.- 
of that array to the current allocation Teve 1.e., the first 
array would be initialized to 1, the second array would be initialized 


to 2, etc.). Use the 'allocation' builtin to determine the depth. 


The program should continue allocating and initializing until the 
user responds with zero (0). Again using the 'allocation' builtin 
to determine the allocation depth, it should then free all the 


allocated arrays, printing each array just before freeing it. 


Test your program asking for arrays of size 1, 2, 3, and 4, 
Observe the order in which the arrays are freed. 
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2. The segment >udd>MEDclass>F15C>si>printit.fortran contains a fortran 
subroutine that accepts a 2 dy 3 array aS an argument and prints 
it out a row at a time. 


Copy the segment, print it, compile it and write a PL/I procedure 
called ‘call _fortran.pli' declaring a 2 by 3 array and the 3 by 2 
transpose of this array (use isubs). The program should: 


a. Initialize the 2 by 3 array as follows: 


1 2 3 
i 4: <9 6 


b. Call the fortran subroutine, passing to it the 
untransposed array. 


e. Call the fortran subroutine, passing to it the 
transposed array. 


Note: 


1) 'printit' must be declared an entry, and since it will be 
passed both a 2.by 3 and a 3 by 2 array, its descriptor must use the 
star convention (dim(*#,*#)). 


2) The aera the array should be declared fixed bin (35) 
s 


Since that i he data type for fortran integers. 


3) The final compilation of the PL/I program will still have a 
"by value" warning since 'isub' defined variables are always passed by 
value. Recall this means that the called procedure will not be able 
to change the variable passed to it. How can this warning be avoided? 
That is, how could the array be passed by reference? 


4) When you compile the PL/I program with the table option (the 


default), you will receive a warning that the transposed array will 
not appear in the symbol table. 
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WORKSHOP TWO 


Based Variables and Areas 


This workshop has three parts. Be sure you understand the mechanism 
used in parts 1 and 2 (based variables), since they form the basis for 
workshop three and the remainder of this course. 


- 


The following declarations are in the segment 
>udd>MEDclass>F 15C>s1>include>w2.inel.pli. 


/* Begin w2.inel.pl1 */ 


del string char (10) varying; 
del 1 string parts based (addr (string)), 
2 length fixed bin (35), 
2 characters char (10); 
del number float binary; 
del 1 float_num based (addr (number)), 
2 sign bit (1) unal, 
2 exponent bit (7) unal, 
2m sign bit (1) unal, 


2 mantissa bit (27) unal; 


/® End w2.inel.pli */ 


Write a short program that. enters data into the two BASE variables. 
(string and number) and then prints out the Values in e BASED 
Coverlay) variables in order to see exactly how ‘char varying’ and 


'float binary' numbers are stored. (Use put data.) 


Change your working directory to >udd>MEDclass>F15C>s1. Print the 
segment get _message.pl1. Execute the corresponding object segment 
and follow the directions given in the message. 


In your working directory create an area named AREA (all caps) 
using the ereate area eommand. . In ' the segment, 
>udd>MEDelass>F 15C>s1>fill_area.pl1, is a program that allocates 2 
numbers in that area. Print the program and make sure you understand 
what it is doing. Execute the object segment. Use the dump segment 
(ds) command to look at your AREA segment. Notice how the pointer 
values printed by the program correspond to locations in the segment. 
Also notice the extra area manager information in the segment. 


Not To Be Reproduced W-3 F15C 


WORKSHOP THREE 


Gaining Direct Access to a Segment 


The segment, >udd>MEDclass>Fi5C>si>invoices, contains invoices for a 
number of differént vendors. .At the base of the segment is a header. 
The remainder of the segment is a series of linked structures, each 
one representing a single invoice for a particular vendor. The declaration 


to be used for the linked structure is: 


del 1 invoice based (p), 
~~ 2 next bit (18), 
2 invoice number dec (3), 
2 vendor_number dee (3), 
2 charge fixed dec (8,2); 


The structure member, invoice.next, is a non-standard offset (word 
offset from the base of the segment) indicating the location of the 
next structure in the linked list. : 


(get_invoices.pl1¥. Your program should prompt 


Write a program called 

the user for a vendor number-(3-digies}-and then print out all invoice 
numbers and the corresponding charges belonging to that vendor. 
a ee ee 
Actually, the segment does not contain just one linked list. There 
are, in fact, 10 linked lists below the header. The header is used to 
determine which list is to be searched for that particular vendor. 
The declaration to be used for the header is: 


del 1 invoice file header based (seg ptr), 
| 2 number_of invoices fixed bin, 
2 hash_table (0:9) bit (18) unal; 


The hash table is made up of 10 non-standard offsets. Each offset 
points to the start of one of the linked lists of invoice structures. 
Which linked list a particular vendor is found in is determined by the 
last digit in the vendor number. For example, invoices for vendor 35] 
would be in the list pointed to by ‘hash_table({7)'. — 


Thus, when a user gives you a vendor number you must ell +e 
| str re at the base o he segment and get the offset for the 


sta of the appropriate Linked list. Then you must_get a pointer to 
the start of the linked move the invoice structure down the 
Tist_checking-for-the appropriate andor tithe vendor aatches nine 
Out the invoice number an he charge. ontinue scanning e list 
,»Until you reach the end. e last invoige in any list is indicated by 
invoice.next = "0"b. 
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WORKSHOP THREE 


As an example, to find invoices for vendor 357, the statement p = 
ptr(seg_ptr,hash_table(7)) would generate a pointer 'p' which locates 
the first invoice for a vendor with low order digit 7. The vendor 
number for this invoice can be compared to 357, and printed out if 
matched. Then, the pointer p could be adjusted to the next invoice in 
this list by coding the statement p = ptr(seg ptr, p ->next) and so 
——eee Nr 
on. 


Test your program by printing out the invoice number and charges of 


all invoices for vendor number 029, 


You may wish to use the following declarations which are in the segment, 
>udd>MEDelass>F 15C>s1>include>w3.incl.pl1. 
OE ee nS Se pe ee eg a ge 


/* Begin w3.incl.pl1 */ 


del initiate file. entry (char (*), char (*), bit (*), pointer, 
fixed bin (24), fixed bin (35)); 


del code fixed bin (35); 
del bit count fixed bin (24); 
del seg ptr ‘ptr; 
del p ptr ;. 


del 1 invoice file_header based (seg ptr), 
2 number of invoices fixed bin, 
2 hash_table (0:9) bit (18) unaligned; 


del 1 invoice based (p) aligned, 
2 next. bit (18), 
2 invoice number dec (3), 
2 vendor_number dec (3), 


2 charge fixed dec (8,2); 
del com_err_ entry options (variable); 
del (sysin, 
sysprint) file; 


/* End w3.inel.pli */ 


For the more curious, you may wish to study 
2? udd>MEDclass>F i5C>si>set_up> put_invoice.pii. 
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WORKSHOP FOUR 
The Multics Condition Handling Mechanism 


Print the segment >udd>MEDclass>F 15C>s1>test any _other.pl1 (tao.pl1) 
and execute the corresponding object segment. 


Examine your user stack using the '‘'stack' request of ‘probe’. 


“Notice where, on the stack, the program you just executed is compared 


to the 'wall' laid down by default error handler. 


Using the 'signal' command, execute the following commands: "signal 
zerodivide", "signal any_other", "signal finish", "signal 
program interrupt". How do you explain the difference in these 
four cases? 


Note: the above program is not well behaved in that it should 
have continued to signal the 'finish' condition. 


BE SURE TO DO A ‘release -all' BEFORE PROCEEDING!!! 


Print the segment >udd>MEDclass>F 15C>s1>test_cleanup.pii (tcu.pl1) 
and execute the corresponding object segment TWO times. BE SURE 
YOU EXECUTE IT AT LEAST TWO TIMES (more than two won't hurt, but 
is wasteful). 


Examine the user stack using the 'stack' request of 'probe'. Notice 
the numerous occurrences of 'test cleanup’ on the stack. Now examine 
the Stack using the 'trace_ stack’ “(ts) command. Notice the ‘cleanup’ 
handlers in several stack frames. (While you are at it, alse 
notice that 'initialize process ' and 'default_error_handier_' have 
only one condition handler.) 


Execute a "release -all". Can you explain what happened? 

Print the segment >udd>MEDclass>F 15C>s1>test_finish_1.pl1 (tf1.p11) 
and execute the corresponding object segment AT LEAST THREE TIMES. 
Signal the finish condition. 


Do a “release -all" and then repeat the above procedure using 
>udd>MEDelass>F15C>si>test_finish_2.pl1 (tf2.pli). 
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IOCB structure 


1. Print the segment >udd>MEDclass>F 15C>si>examine iocb.pl1 and read 
it carefully to see what it does. 


2. Execute the print_attach_table (pat) command to examine the switches 
currently attached. 


3. While in your own directory, execute the following command lines: 


io_call attach zoo vfile_ zoo 
1o_ call open zoo stream | out put 
pat 


Now execute the program >udd>MEDclass>F15C>sl>examine_iocb and 
carefully examine the results. Notice that all pointers and entry 
points printed are in one of 3 segments. 


4, Recall that the list_reference names (lrn) command, if given a 


segment number, will “return the pathname and Warspenas names of 


BS WEES Ww Wwe 


that segment. Use this command to determine the three segments 
whose numbers were found in the IOCB. Notice especially which 
entries in the IOCB point to iox_ and which point to the I[/0 
module, vfile_. Do these make sense, considering the file is 
opened for stream output? 


5. Execute the command line, 'io_ call close zoo'. Again execute the 
'pat' command. Run the program, examine_ iocb, again and notice 
the different results. van. you explain what happened? If not, 
ask your instructor. 


6. Now that you have looked directly at an iocb using an overlay, 
you should try using the command that gives you the same information. 
Execute the command line 'io_ call print_iocb zoo'. 


7. Using ‘io_call print_iocb <switch>' one can easily look at the 
contents of an iocb. Try the following: delete the segment zoo, 
and then use io_call to open zoo "keyed sequential output" and to 
display the contents of the iocb. 
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Multics I/0 Workshop 


ee ee ee 
Write a PL/I procedure calied G Tue ky number .pli3 which _prompts the 
user for a6 digit number, and uses that as a key into an indexed file 
of lucky numbers. The file of numbers is in the segment: 
@ >udd>MEDeclass>F 15C>s1>lucky_nos 
The data records are 32 characters or less in length. 


Display the records. Do not use any language-level I/0. Use only 
iox_ and ioa_ calls in your program. 


Test your program with the numbers 780101, 780116, and 771225. 


You may wish to use the following declarations which are in the segment, 
>udd>MEDclass>F 15C>s1>include>w6.inecl.pli 


"/® Begin w6.inel.pli */ 


del iox_$attach_name entry (char (*), ptr, char (*), ptr, 
fixed bin (35)); 


del iox_$close entry (ptr, fixed bin (35)); 
del iox_ $detach_iocb entry (ptr, fixed bin (35)); 
del iox_$open entry (ptr, fixed bin, bit (1) aligned, 


fixed bin(35)); 

del iox_$read_record entry (ptr, ptr, fixed bin (21), 

fixed bin (21), fixed bin (35)); 
del iox $seek_key entry (ptr, char (256) varying, 

fixed bin (21), fixed bin (35)); 
del iox $get_line entry (ptr, ptr, fixed bin (21), 

~ fixed bin (21), fixed bin (35)); 

del iox $user_input external static ptr; | 
del (ioa , 


com_err_) ' entry options (variable); 
del error_table $no_record fixed bin (35) external; 
del code fixed bin (35); 
del buff char (32); 
del buff ptr ptr; 
del rec_Ten fixed bin (21); 
dcl icocb ptr ptr; 
del n_read fixed bin (21); 
del number char (256) varying; 
del cleanup condition; 
del (addr, 
null, 
sub str) builtin; 


/* End w6.inel.pl1 */ 
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Be sure that you provide an 'on_unit' for the 'cleanup' condition. 
Also, you should check for the @6de, error_table $no record (indicating 
an invalid key), after doing the seek_key. 
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WORKSHOP SEVEN 
A Storage System Workshop 


Apply the concepts discussed in Topic Ten by writing a PL/I procedure 
called 'new_subsystem.pl1' which, when invoked, will do the following: 
— 


1. Determine whether or not a subdirectory called "Fi5C" exists j 
the callers default working directory. If it does, proceed to 
s below. If it does not, proceed to €ask 2yybelow. af a 
or link called "F15C" exists in the Can per Se fault Working 
directory, delete/unlink it, notify the caller of your action, an 
proceed to~step 2 ad ae 


(2) Since no "Fi5C" subdirectory exists in the caller's default working 
directory, create this directory. You should make sure that, besides 


TT TI AAS: 2 ANE ay, 


the standard ACL entries, the directory also has an ACL entry 
giving "sma" ac s_to Student 01.#.*. Report the creation of 
this directory to the caller. a 


é Change the caller's werking directory to the "FI5sc! directory, and 
noti of this action. 


Compile and test out your procedure. 


(CONTINUED ON NEXT PAGE) 
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J 


You may wish to use the following declarations which are in the segment, 
>udd>MEDclass>F 15C>si>include>w7.incl.pli. 


/* Begin w7.incl.pli */ 


—del 
-del 
“del 


del 


del 
del 
del 
del 
del 


del 
del 
del 
del 


del 


delete $path entry (char (*), char (*), bit (6), char (*), 
fixed bin (35)); 
hes $add_dir_acl_entries entry (char (#), char (*), ptr, 
fixed bin, fixed bin (35)); 
hes $append_branchx entry (char (*), char (*), fixed bin (5), 
(3) fixed bin (3), char (#*), fixed bin Cy, fixed bin (1), 
fixed bin (24), fixed bin (35)); 
hes $status_minf entry (char (*), char (#), fixed bin (1), 
fixed bin (2), fixed bin (24), fixed bin (35)); 
get_group_id $tag_ star entry returns (char (32)); 


get_ default_ wdir_ entry returns (char (168) aligned); 

change _wdir_ entry (char (168), fixed bin (35)); 

ab solute _pathname_ entry (char (*), char (*), fixed bin (35)); 
Cioa_ 

com_ Terr_ ) entry options (variable); 


error_ table $nomatch fixed bin (35) external; 

error_table $noentry fixed bin.(35) external; 

addr builtin; 

rings (3) fixed bin (3) internal static init (4, 4, 
| options (constant); | 

1 dir_acl aligned, 


2 access name char (32) init ("Student _01.*.*"), 
2 dir_modes bit (36) init ("111"b), 
2 status_code fixed bin (35); 


/*® End w7.incl.pli #/ 


4) 
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WORKSHOP EIGHT 


Write a PL/I procedure called "my tmsr.pli" that will prompt the 
user for a reference name to be terminated. Using the appropriate 


entry point in term, duplicate. the action of the 
terminate single refname command (i,e. terminate the reference name, 
but do not make the segment unknown unless it was the last refname 
in the RNT for that segment). The program should end by notifying 


the user that the termination is complete.INCLUDE IN THE MESSAGE, 
THE ABSOLUTE PATHNAME OF THE SEGMENT ASSOCIATED WITH THAT REFNAME. 


Execute a simple command (ex. who, memo, pwd, list). Test your 
program using that reference name as input. : 


3.¢# Look at the contents of Sudd>MEDelass>F 15C>s1>eall sub1l.pli and 


4, 


46> udd>MEDeLass>F 15C>s1>sub1.pl1. At command level, initiate the 


object segment for the first program with the reference name "csi" 


re OCTInitiate >udd>MEDclass>F15C>s1i>call_sub1 csi"). Now execute the 


program by simply ing "esi". This, of course, works no matter 
what your working directory 1s at the time of initiation or execution. 


Use your "my _tmsr" procedure to terminate the reference name "subi". 
Again execute thé call_sub1 program using the name "csi". It should 
work exactly as it did before. 
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Writing a Command/ Active Function 


It is to return the entryname 
of 1 a segment supplied as an argument. 

That is, issuing the command 

x parent >udd>MEDclass>F 15C>s1>foo 


would result in 'si' being output to the terminal. Used as an 
active function 


( {parent >udd>MEDclass>F 15C>s1>foo] 
it would return the string 'si'. 


Note of course, the argument needn't be an absolute pathname. 
Try your command out on various segments. 


Test it's ability to work as an active function by issuing the 


ls 
command: 


status <[parent ?7] 


Test your program both as a ‘command’ and as an ‘active function' 
giving it the wrong number of arguments. 
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You may wish to use the following declarations which are in the segment, 
>udd>MEDclass>F 15C>si>include>w9.incl.pli. 


/*Begin—wo,inel,pl1 */ 


del cu_$arg_ptr entry (fixed bin, ptr, fixed bin, 
fixed bin (35)); 
del cu_$af_return_arg entry (fixed bin, ptr, fixed bin (21), 
fixed bin (35)); 
del expand_pathname_ entry (char (*), char (*), char (*), 
fixed bin (35)); 
del complain entry variable options (variable); 
del (ioa , 
com_ err , 
active fne_err_) entry options (variable); 
del error_ table _ $wrong__ no_of args external fixed bin (35); 
del nargs fixed bin; 
del (arg ptr, 
rtn_ string ptr) ptr; 


del rtn _ string char (max_length) varying 
based (rtn_string_ptr); 

del arg char (arg len) based (arg_ptr); 

dei max_length fixed bin (21); 

del arg ~ len fixed bin; 

del code fixed bin (35); 

del af bit (1) init ("0"b); 

del ME ehar (6) static init ("parent") 
options (constant); 

del entr yname char (32); 

del dir_name ehar (256); 

7*-End—w9inel.pli */ 
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